/ Hex Artifact Content
Login

Artifact 155fea14c0747f8842c4e592e04734f47ad8218d0f33c511849b15d410a7fb5c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
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 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<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 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f7c0: 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20 66 6c 61  CESS_READ.** fla
f7d0: 67 20 69 73 20 6e 65 76 65 72 20 61 63 74 75 61  g is never actua
f7e0: 6c 6c 79 20 75 73 65 64 20 61 6e 64 20 69 73 20  lly used and is 
f7f0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
f800: 69 6e 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  in the built-in.
f810: 2a 2a 20 56 46 53 65 73 20 6f 66 20 53 51 4c 69  ** VFSes of SQLi
f820: 74 65 2e 20 20 54 68 65 20 66 69 6c 65 20 69 73  te.  The file is
f830: 20 6e 61 6d 65 64 20 62 79 20 74 68 65 20 73 65   named by the se
f840: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 61 6e  cond argument an
f850: 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  d can be a.** di
f860: 72 65 63 74 6f 72 79 2e 20 54 68 65 20 78 41 63  rectory. The xAc
f870: 63 65 73 73 20 6d 65 74 68 6f 64 20 72 65 74 75  cess method retu
f880: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f890: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 73 6f  on success or so
f8a0: 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 65  me.** non-zero e
f8b0: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 74 68 65  rror code if the
f8c0: 72 65 20 69 73 20 61 6e 20 49 2f 4f 20 65 72 72  re is an I/O err
f8d0: 6f 72 20 6f 72 20 69 66 20 74 68 65 20 6e 61 6d  or or if the nam
f8e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 69 6c 65  e of.** the file
f8f0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73 65   given in the se
f900: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f910: 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66 20 53 51   illegal.  If SQ
f920: 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73 20 72 65  LITE_OK.** is re
f930: 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 6e  turned, then non
f940: 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f 20 69 73  -zero or zero is
f950: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
f960: 52 65 73 4f 75 74 20 74 6f 20 69 6e 64 69 63 61  ResOut to indica
f970: 74 65 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  te.** whether or
f980: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 69 73   not the file is
f990: 20 61 63 63 65 73 73 69 62 6c 65 2e 20 20 0a 2a   accessible.  .*
f9a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
f9b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
f9c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
f9d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
f9e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
f9f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
fa00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
fa10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
fa20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
fa30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
fa40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
fa50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
fa60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
fa70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
fa80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
fa90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
faa0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
fab0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
fac0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
fad0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
fae0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
faf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
fb00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
fb10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
fb20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
fb30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
fb40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
fb50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
fb60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
fb70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
fb80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
fb90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
fba0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
fbb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
fbc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
fbd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
fbe0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
fbf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
fc00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
fc10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
fc20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
fc30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
fc40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
fc50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
fc60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
fc70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
fc80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
fc90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
fca0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fcb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
fcc0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
fcd0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
fce0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
fcf0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
fd00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
fd10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
fd20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
fd30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
fd40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
fd50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
fd60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
fd70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
fd80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
fd90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
fda0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
fdb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fdc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
fdd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
fde0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
fdf0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
fe00: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
fe10: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
fe20: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
fe30: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
fe40: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
fe50: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
fe60: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fe70: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
fe80: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
fe90: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
fea0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
feb0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
fec0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
fed0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
fee0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
fef0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
ff00: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
ff10: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
ff20: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
ff30: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ff40: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
ff50: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
ff60: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
ff70: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
ff80: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
ff90: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
ffa0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
ffb0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
ffc0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
ffd0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
ffe0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
fff0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10000 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10010 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10020 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10030 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10040 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10050 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10060 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10070 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10080 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10090 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
100a0 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
100b0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
100c0 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
100d0 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
100e0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
100f0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
10100 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
10110 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
10120 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
10130 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
10140 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
10150 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
10160 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
10170 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
10180 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10190 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
101a0 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
101b0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
101c0 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
101d0 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
101e0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
101f0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
10200 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
10210 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
10220 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
10230 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
10240 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
10250 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
10260 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
10270 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
10280 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10290 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
102a0 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
102b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
102c0 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
102d0 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
102e0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
102f0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
10300 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
10310 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
10320 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
10330 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
10340 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
10350 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
10360 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
10370 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
10380 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
10390 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
103a0 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
103b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
103c0 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
103d0 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
103e0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
103f0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
10400 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
10410 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
10420 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
10430 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
10440 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
10450 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
10460 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
10470 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
10480 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10490 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
104a0 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
104b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
104d0 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
104e0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
104f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10500 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10510 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
10520 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
10530 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10540 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10550 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
10560 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
10570 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10590 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
105a0 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
105b0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
105c0 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
105d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
105e0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
105f0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
10600 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
10610 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
10620 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
10630 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
10640 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
10650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
10660 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
10670 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
10680 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
10690 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
106a0 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
106b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
106c0 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
106d0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
106e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
106f0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
10700 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
10710 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
10720 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
10730 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
10740 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
10750 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
10760 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
10770 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
10780 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
10790 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
107a0 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
107b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
107c0 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
107d0 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
107e0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
107f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
10800 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
10810 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
10820 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
10830 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10840 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10850 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
10860 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
10870 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
10880 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
10890 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
108a0 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
108b0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
108c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
108d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
108e0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
108f0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
10900 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
10910 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
10920 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
10930 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10940 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
10950 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
10960 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10970 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10980 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
10990 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
109a0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
109b0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
109c0 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
109d0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
109e0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
109f0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
10a00 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
10a10 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
10a20 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
10a30 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
10a40 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
10a50 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
10a60 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
10a70 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
10a80 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
10a90 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
10aa0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
10ab0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
10ac0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
10ad0 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
10ae0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
10af0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
10b00 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
10b10 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
10b20 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
10b30 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10b40 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
10b50 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10b60 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
10b70 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10b80 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
10b90 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
10ba0 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
10bb0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
10bc0 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
10bd0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10be0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10bf0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
10c00 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
10c10 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10c20 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
10c30 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
10c40 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
10c50 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
10c60 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
10c70 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
10c80 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10c90 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
10ca0 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
10cb0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
10cc0 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
10cd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
10ce0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
10cf0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
10d00 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
10d10 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10d20 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10d30 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
10d40 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10d50 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10d60 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
10d70 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
10d80 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
10d90 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
10da0 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
10db0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
10dc0 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
10dd0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
10de0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
10df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e00 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
10e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10e20 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10e30 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
10e40 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
10e50 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
10e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e70 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
10e80 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
10e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10ea0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
10eb0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
10ec0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
10ed0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
10ee0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
10ef0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
10f00 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
10f10 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
10f20 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
10f30 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
10f40 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
10f50 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
10f60 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
10f70 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
10f80 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
10f90 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
10fa0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
10fb0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10fd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10fe0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
10ff0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11000 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11010 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11020 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11030 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11040 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11050 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11060 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11070 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11080 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11090 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
110a0 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
110b0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
110c0 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
110d0 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
110e0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
110f0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
11100 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11110 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
11120 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
11130 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
11140 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
11150 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
11160 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
11170 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
11180 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11190 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
111a0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
111b0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
111c0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
111d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
111e0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
111f0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
11200 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
11210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
11220 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
11230 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
11240 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
11250 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
11260 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
11270 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
11280 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
11290 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
112a0 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
112b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
112c0 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
112d0 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
112e0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
112f0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
11300 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
11310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11320 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
11330 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
11340 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
11350 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11360 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
11390 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
113a0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
113b0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
113c0 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
113d0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
113e0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
113f0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
11400 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
11410 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
11420 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
11430 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
11440 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
11450 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
11460 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
11470 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
11480 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
11490 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
114a0 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
114b0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
114c0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
114d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
114e0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
114f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11500 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
11510 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
11520 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
11530 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
11540 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
11550 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
11560 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
11570 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
11580 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
11590 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
115a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
115b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
115c0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
115d0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
115e0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
115f0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
11600 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
11610 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
11620 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11630 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
11640 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
11650 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
11660 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11670 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11680 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
11690 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
116a0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
116b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
116c0 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
116d0 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
116e0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
116f0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
11700 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
11710 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11720 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
11730 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
11740 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
11750 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
11760 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
11770 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11790 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
117a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
117b0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
117c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
117d0 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
117e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
11800 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
11810 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
11820 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
11830 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
11840 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
11850 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
11860 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
11870 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
11880 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
11890 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
118a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
118b0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
118c0 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
118d0 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
118e0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
118f0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11900 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
11910 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
11920 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
11930 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
11940 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
11950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11960 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
11970 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
11980 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
11990 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
119a0 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
119b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
119d0 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
119e0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
119f0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
11a00 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
11a10 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
11a20 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
11a30 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
11a40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
11a50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
11a60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
11a70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11a80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
11a90 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
11aa0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
11ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11ac0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
11ae0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
11af0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
11b00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11b10 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
11b20 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
11b30 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
11b40 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
11b60 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11b70 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
11b80 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
11b90 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
11ba0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
11bb0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
11bc0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
11bd0 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
11be0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
11bf0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11c00 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
11c10 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
11c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11c30 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
11c40 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
11c50 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
11c60 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
11c70 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
11c80 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
11c90 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
11ca0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
11cb0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
11cc0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11cd0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11ce0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
11cf0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
11d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
11d10 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
11d20 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
11d30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11d40 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
11d50 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
11d60 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
11d70 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
11d80 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
11d90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
11da0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
11db0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
11dc0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
11dd0 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
11de0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11df0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
11e00 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
11e10 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
11e20 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
11e30 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
11e40 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11e60 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
11e70 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
11e80 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
11e90 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
11ea0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
11eb0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
11ec0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
11ed0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
11ee0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
11ef0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11f00 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
11f10 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
11f20 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
11f30 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
11f40 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
11f50 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
11f60 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
11f70 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11f80 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
11f90 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
11fa0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
11fb0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
11fc0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
11fd0 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
11ff0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12000 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12010 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12020 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12030 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12050 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12060 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12070 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12080 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12090 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
120a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
120b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
120c0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
120e0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
120f0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12100 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12110 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
12120 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
12130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
12140 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
12150 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
12160 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
12170 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12180 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12190 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
121a0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
121b0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
121c0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
121d0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
121e0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
121f0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
12200 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
12210 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
12220 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
12230 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
12240 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
12250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12260 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
12270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12280 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
12290 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
122a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
122b0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
122c0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
122d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
122e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
122f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
12300 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
12310 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
12320 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
12330 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
12340 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
12350 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
12360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12370 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
12380 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
12390 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
123a0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
123b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
123c0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
123d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
123e0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
123f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
12400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12410 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12420 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
12430 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
12440 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12450 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
12460 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
12470 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
12480 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
12490 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
124a0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
124b0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
124c0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
124d0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
124e0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
124f0 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
12500 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
12510 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
12520 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
12530 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
12540 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
12550 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
12560 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12570 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
12580 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
12590 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
125a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
125b0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
125d0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
125e0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
125f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12600 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
12610 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
12620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
12630 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
12640 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
12650 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
12660 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
12670 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
12680 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
12690 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
126a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
126b0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
126c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
126d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
126e0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
126f0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
12700 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
12710 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
12720 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
12730 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
12740 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
12750 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
12760 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
12770 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
12780 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
12790 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
127a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
127b0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
127c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
127d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
127e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
127f0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
12800 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
12810 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
12820 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
12830 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
12840 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
12850 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
12860 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12870 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
12880 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
12890 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
128a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
128b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
128c0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
128d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
128e0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
128f0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
12900 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
12910 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
12920 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
12930 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
12940 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
12950 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
12960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
12970 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
12980 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
12990 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
129a0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
129b0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
129c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
129d0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
129e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
129f0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
12a00 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12a10 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12a30 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
12a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12a50 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
12a60 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
12a70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12a80 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
12a90 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
12aa0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
12ab0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
12ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
12ad0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
12ae0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
12af0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
12b00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12b10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
12b20 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
12b30 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
12b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
12b50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
12b60 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
12b70 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
12b80 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
12b90 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
12ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12bb0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
12bc0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
12bd0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
12be0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12bf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12c00 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
12c10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
12c20 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
12c30 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
12c40 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
12c50 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
12c60 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
12c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14bf0 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  L_MALLOC]] <dt>S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c10 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  LL_MALLOC</dt>.*
14c20 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14c30 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
14c40 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14c50 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
14c60 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69  ent of.** type i
14c70 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
14c80 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
14c90 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76  ich if true prov
14ca0 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a  ides a hint to.*
14cb0 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  * SQLite that it
14cc0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61   should avoid la
14cd0 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14ce0 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62  ations if possib
14cf0 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  le..** SQLite wi
14d00 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66  ll run faster if
14d10 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d   it is free to m
14d20 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79  ake large memory
14d30 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a   allocations,.**
14d40 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63   but some applic
14d50 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66  ation might pref
14d60 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72  er to run slower
14d70 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72   in exchange for
14d80 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61  .** guarantees a
14d90 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67  bout memory frag
14da0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61  mentation that a
14db0 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c  re possible if l
14dc0 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  arge.** allocati
14dd0 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e  ons are avoided.
14de0 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
14df0 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20  ormally off..** 
14e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14e20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
14e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14e40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
14e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14e60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
14e70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
14e80 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14e90 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14ea0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14eb0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14ec0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14ed0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14ef0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14f00 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14f20 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14f30 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
14f40 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
14f50 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
14f60 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
14f70 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
14f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14f90 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14fa0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14fb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14fc0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14fd0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14fe0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14ff0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
15000 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
15010 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
15020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
15030 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
15040 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
15050 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
15060 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
15070 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
15080 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
15090 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
150a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
150b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
150c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
150d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
150e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
150f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
15100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15110 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
15120 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
15130 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
15140 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
15150 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e  r used..** </dd>
15160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15170 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
151a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
151b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
151c0 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
151d0 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
151e0 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
151f0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
15200 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
15210 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
15220 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
15230 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15240 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
15250 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15260 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
15270 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
15280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
15290 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
152a0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
152b0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
152c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152d0 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
152e0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
152f0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15300 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
15310 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
15320 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15330 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
15340 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
15350 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
15360 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
15370 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
15380 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
15390 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
153a0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
153b0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
153c0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
153d0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
153e0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
153f0 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
15400 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
15410 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
15420 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
15430 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
15440 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
15450 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
15460 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
15470 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
15480 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15490 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
154a0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
154b0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
154c0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
154d0 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
154e0 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
154f0 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
15500 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
15510 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
15520 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
15530 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
15540 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
15550 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
15560 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15570 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
15580 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
15590 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
155a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
155b0 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
155c0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
155d0 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
155e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
155f0 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
15600 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
15610 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
15620 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
15630 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
15640 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
15650 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
15660 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
15670 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
15680 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
15690 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
156a0 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
156b0 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
156c0 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
156d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
156e0 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
156f0 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
15700 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15710 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
15720 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15730 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
15740 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
15750 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
15760 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
15770 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
15780 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
15790 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
157a0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
157b0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
157c0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
157d0 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
157e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
157f0 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
15800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15810 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
15820 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
15830 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
15840 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15850 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15860 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15870 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
158a0 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
158b0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
158c0 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
158d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
158e0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
158f0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
15900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15910 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
15920 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
15930 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15940 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15950 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15960 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
15970 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
15980 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
15990 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
159a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
159b0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
159c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
159d0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
159e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
159f0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
15a00 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
15a10 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
15a20 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15a40 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
15a50 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
15a60 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
15a70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
15a80 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
15a90 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
15aa0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15ab0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
15ac0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
15ad0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15ae0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
15af0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
15b00 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
15b10 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
15b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
15b30 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
15b40 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
15b50 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
15b60 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
15b70 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
15b80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
15b90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
15ba0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
15bb0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
15bc0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
15bd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
15be0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
15bf0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
15c00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
15c10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
15c20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
15c30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
15c40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
15c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15c60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
15c70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
15c80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
15c90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
15ca0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
15cb0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
15cc0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
15cd0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
15ce0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
15cf0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
15d00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
15d10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
15d20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15d40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
15d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d80 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
15d90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15da0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
15db0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
15dc0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15de0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15df0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
15e00 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
15e10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
15e20 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
15e30 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
15e40 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
15e50 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
15e60 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
15e70 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
15e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
15e90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
15ea0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15eb0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15ec0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
15ed0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
15ee0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
15ef0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
15f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15f10 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
15f20 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
15f30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
15f40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15f50 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
15f60 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
15f70 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
15f80 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
15f90 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
15fa0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15fc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
15fd0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
15fe0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ff0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
16000 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
16010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16030 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
16040 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
16060 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16070 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
16080 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16090 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
160a0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
160b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
160c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
160d0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
160e0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
160f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
16100 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
16110 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
16120 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
16130 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
16140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
16150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
16160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
16170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
16180 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
16190 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
161a0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
161b0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
161c0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
161d0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
161e0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
161f0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
16200 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
16210 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
16220 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
16230 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
16240 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
16250 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
16260 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
16270 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
16280 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
16290 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
162a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
162b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
162c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
162d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
162e0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
162f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
16300 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
16310 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
16320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16330 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16350 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
16360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16380 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
16390 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
163a0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
163b0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
163c0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
163d0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
163e0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
163f0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
16400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16410 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
16420 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
16430 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
16440 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
16450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16460 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
16470 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
16480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
16490 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
164a0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
164b0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
164c0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
164d0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
164e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
164f0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
16500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16510 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
16520 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
16530 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
16540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
16550 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
16560 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
16570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16580 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
16590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
165a0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
165b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
165c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
165d0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
165e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
165f0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
16600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16610 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16620 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16630 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
16640 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
16650 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
16660 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
16670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16680 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
16690 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
166a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
166b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
166c0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
166d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
166e0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
166f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16700 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
16710 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16720 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16730 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16740 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16750 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
16760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16770 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16780 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16790 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
167a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
167b0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
167c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
167d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
167e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16800 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16810 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
16820 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
16830 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
16840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
16850 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
16860 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
16870 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
16880 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16890 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
168a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
168b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
168c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
168d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
168e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
168f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16900 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
16910 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
16920 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
16930 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
16940 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
16950 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
16960 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
16970 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
16980 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
16990 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
169a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
169b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
169c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
169d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
169e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
169f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
16a00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16a10 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
16a20 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
16a30 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
16a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16a50 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
16a60 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
16a80 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
16a90 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
16aa0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
16ab0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
16ac0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
16ad0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
16ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16af0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
16b00 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
16b10 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
16b20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
16b30 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
16b40 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
16b50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16b60 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
16b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
16b80 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
16b90 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
16ba0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
16bb0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
16bc0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
16bd0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
16be0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
16bf0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
16c00 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16c10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
16c20 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
16c30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
16c40 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
16c50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
16c60 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
16c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
16c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
16c90 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
16ca0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
16cb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
16cc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16cd0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cf0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
16d00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d10 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
16d20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16d30 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
16d40 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
16d50 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
16d60 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
16d70 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
16d80 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
16d90 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
16da0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16db0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
16dc0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
16dd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
16de0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
16df0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
16e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
16e10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
16e20 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
16e30 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
16e40 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
16e50 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
16e60 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
16e70 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
16e80 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
16e90 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
16ea0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
16eb0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
16ec0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
16ed0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
16ee0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
16ef0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
16f00 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
16f10 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
16f20 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
16f30 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
16f40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
16f50 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16f60 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
16f70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16f80 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
16f90 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
16fa0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
16fb0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
16fc0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
16fd0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
16fe0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
16ff0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
17000 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
17010 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17030 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
17040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17050 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17060 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
17070 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17080 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17090 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
170a0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
170b0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
170c0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
170d0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
170e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
170f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
17100 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
17110 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
17120 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
17130 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
17140 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
17150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
17160 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
17170 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
17180 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
17190 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
171a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
171b0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
171c0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
171d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
171e0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
171f0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
17200 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
17210 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
17220 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
17230 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
17240 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
17250 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
17260 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
17270 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
17280 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
17290 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
172a0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
172b0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
172c0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
172d0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
172e0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
172f0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
17300 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
17310 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
17320 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
17330 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
17340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
17360 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17370 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
17380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17390 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
173b0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
173c0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
173d0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
173e0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
173f0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
17400 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
17410 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
17420 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
17430 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
17440 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17460 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17480 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
17490 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
174a0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
174b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
174c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
174d0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
174e0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
174f0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
17500 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17510 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
17520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
17530 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
17540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
17550 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
17560 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
17570 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
17580 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
17590 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
175a0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
175b0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
175c0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
175d0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
175e0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
175f0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
17600 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
17610 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
17620 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17630 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
17640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17650 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
17660 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17670 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
17680 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
17690 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
176a0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
176b0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
176c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
176d0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
176e0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
176f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
17700 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
17710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
17720 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17730 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
17740 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
17750 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
17760 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17770 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
17780 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
17790 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
177a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
177b0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
177c0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
177d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
177e0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
177f0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
17800 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
17810 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
17820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
17830 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
17840 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
17850 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
17860 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
17870 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
17880 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
17890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
178a0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
178b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
178c0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
178d0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
178e0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
178f0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
17900 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
17910 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
17920 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
17930 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
17940 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
17950 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
17960 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
17970 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
17980 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
17990 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
179a0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
179b0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
179c0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
179d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
179e0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
179f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
17a10 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
17a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
17a30 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
17a40 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
17a50 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
17a60 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
17a70 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
17a80 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
17a90 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
17aa0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
17ab0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
17ac0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
17ad0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
17ae0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
17af0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
17b00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17b10 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
17b20 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
17b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
17b40 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
17b50 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
17b60 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
17b70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
17b80 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
17b90 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17ba0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
17bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17bc0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
17bd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17be0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17bf0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
17c00 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17c10 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
17c20 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
17c30 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
17c40 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
17c50 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
17c60 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
17c70 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
17c80 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17c90 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
17ca0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
17cb0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
17cc0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
17cd0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
17ce0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
17cf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17d00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17d10 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
17d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17d30 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
17d40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17d50 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17d60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17d70 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
17d80 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
17d90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17da0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
17db0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
17dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
17dd0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
17de0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
17df0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
17e00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
17e10 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
17e20 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
17e30 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
17e40 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
17e50 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
17e60 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
17e70 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
17e80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
17e90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17ea0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
17eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17ec0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
17ed0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17ee0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
17ef0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17f00 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17f10 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
17f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
17f30 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
17f40 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
17f50 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
17f60 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
17f70 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
17f80 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
17f90 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
17fa0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17fb0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
17fc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17fd0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
17fe0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
17ff0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
18000 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
18010 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
18020 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
18030 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
18040 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
18050 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
18060 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
18070 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
18080 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
18090 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
180a0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
180b0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
180c0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
180d0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
180e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ue..**.** [[SQLI
180f0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18100 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64  NL_SPILL]].** <d
18110 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18120 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a  STMTJRNL_SPILL.*
18130 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18140 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
18150 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74  L_SPILL option t
18160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
18170 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
18180 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74   becomes the [st
18190 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d  atement journal]
181a0 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74   spill-to-disk t
181b0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b  hreshold.  .** [
181c0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  Statement journa
181d0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20  ls] are held in 
181e0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65  memory until the
181f0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65  ir size (in byte
18200 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68  s).** exceeds th
18210 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74  is threshold, at
18220 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65   which point the
18230 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f  y are written to
18240 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20   disk..** Or if 
18250 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73  the threshold is
18260 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a   -1, statement j
18270 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61  ournals are alwa
18280 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75  ys held.** exclu
18290 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79  sively in memory
182a0 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20  ..** Since many 
182b0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
182c0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20  ls never become 
182d0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74  large, setting t
182e0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65  he spill.** thre
182f0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65  shold to a value
18300 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63   such as 64KiB c
18310 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63  an greatly reduc
18320 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a  e the amount of.
18330 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20  ** I/O required 
18340 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65  to support state
18350 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ment rollback..*
18360 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
18370 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74  lue for this set
18380 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c  ting is controll
18390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  ed by the.** [SQ
183a0 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  LITE_STMTJRNL_SP
183b0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ILL] compile-tim
183c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e option..**.** 
183d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
183e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d 5d  SORTERREF_SIZE]]
183f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
18400 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f  ONFIG_SORTERREF_
18410 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  SIZE.** <dd>The 
18420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18430 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 74  RTERREF_SIZE opt
18440 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69  ion accepts a si
18450 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ngle parameter.*
18460 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29 20  * of type (int) 
18470 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65 20  - the new value 
18480 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72 65  of the sorter-re
18490 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
184a0 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 6c  eshold..** Usual
184b0 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ly, when SQLite 
184c0 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61 6c  uses an external
184d0 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 72   sort to order r
184e0 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e 67  ecords according
184f0 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 20  .** to an ORDER 
18500 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 66  BY clause, all f
18510 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20 62  ields required b
18520 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72 65  y the caller are
18530 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 0a   present in the.
18540 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64  ** sorted record
18550 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  s. However, if S
18560 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
18570 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64 65   based on the de
18580 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 6f  clared type.** o
18590 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  f a table column
185a0 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65 73   that its values
185b0 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
185c0 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20 6c  e very large - l
185d0 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 68  arger.** than th
185e0 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f 72  e configured sor
185f0 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69  ter-reference si
18600 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 74  ze threshold - t
18610 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65 0a  hen a reference.
18620 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  ** is stored in 
18630 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63 6f  each sorted reco
18640 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75 69  rd and the requi
18650 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  red column value
18660 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f 6d  s loaded.** from
18670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 73   the database as
18680 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65 74   records are ret
18690 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 20  urned in sorted 
186a0 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61 75  order. The defau
186b0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20  lt.** value for 
186c0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 74  this option is t
186d0 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69 73  o never use this
186e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 53   optimization. S
186f0 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a 20  pecifying a .** 
18700 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 72  or this option r
18720 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61  estores the defa
18730 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a 2a  ult behaviour..*
18740 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  * This option is
18750 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
18760 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
18770 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
18780 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
18790 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e 43  _SORTER_REFERENC
187a0 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ES] compile-time
187b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b   option..**.** [
187c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
187d0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a 2a  EMDB_MAXSIZE]].*
187e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
187f0 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18800 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  E.** <dd>The SQL
18810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42  ITE_CONFIG_MEMDB
18820 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e 20  _MAXSIZE option 
18830 61 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65  accepts a single
18840 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b 73   parameter.** [s
18850 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 70 61  qlite3_int64] pa
18860 72 61 6d 65 74 65 72 20 77 68 69 63 68 20 69 73  rameter which is
18870 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78   the default max
18880 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72 20 61 6e  imum size for an
18890 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
188a0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
188b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64 65  sing [sqlite3_de
188c0 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20 54  serialize()].  T
188d0 68 69 73 20 64 65 66 61 75 6c 74 20 6d 61 78 69  his default maxi
188e0 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e 20  mum.** size can 
188f0 62 65 20 61 64 6a 75 73 74 65 64 20 75 70 20 6f  be adjusted up o
18900 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69 76  r down for indiv
18910 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 73 20  idual databases 
18920 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
18930 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
18940 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33 5f  LIMIT] [sqlite3_
18950 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69 6c  file_control|fil
18960 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66 20  e-control].  If 
18970 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
18980 61 74 69 6f 6e 20 73 65 74 74 69 6e 67 20 69 73  ation setting is
18990 20 6e 65 76 65 72 20 75 73 65 64 2c 20 74 68 65   never used, the
189a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61  n the default ma
189b0 78 69 6d 75 6d 20 69 73 20 64 65 74 65 72 6d 69  ximum is determi
189c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
189d0 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46 41  QLITE_MEMDB_DEFA
189e0 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f 6d  ULT_MAXSIZE] com
189f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18a00 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a 20 63 6f  .  If that.** co
18a10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18a20 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c 20 74 68  n is not set, th
18a30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  en the default m
18a40 61 78 69 6d 75 6d 20 69 73 20 31 30 37 33 37 34  aximum is 107374
18a50 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  1824..** </dl>.*
18a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
18a80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
18a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
18ab0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
18ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ad0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
18ae0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
18af0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
18b10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
18b20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18b30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18b50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
18b60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
18b70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
18b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18b90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
18ba0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
18bb0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
18bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
18bd0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
18be0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
18bf0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
18c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
18c10 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
18c20 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
18c30 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
18c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c50 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
18c60 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
18c90 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
18ca0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
18cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18cd0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
18ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
18cf0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
18d00 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
18d10 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
18d20 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
18d30 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18d50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
18d60 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
18d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
18d90 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
18da0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
18dc0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
18dd0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
18df0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
18e00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
18e10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18e20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
18e30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
18e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18e60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
18e70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
18e80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
18e90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ea0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
18eb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18ec0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18ee0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
18ef0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
18f00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
18f20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
18f30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
18f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
18f60 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
18f80 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
18f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18fa0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18fb0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
18fc0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18fd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18fe0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
18ff0 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
19000 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
19010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19020 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
19030 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
19040 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
19050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19060 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
19070 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
19080 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
19090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
190a0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
190b0 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62          27  /* b
190c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
190d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
190e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20  SORTERREF_SIZE  
190f0 20 20 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e      28  /* int n
19100 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
19110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
19120 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20 20 20 20  MDB_MAXSIZE     
19130 20 20 32 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    29  /* sqlite3
19140 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  _int64 */../*.**
19150 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
19160 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
19170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
19180 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
19190 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
191a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
191b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
191c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
191d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
191e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
191f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
19210 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
19220 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
19230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
19250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
19260 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
19270 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
19280 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
19290 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
192a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
192b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
192c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
192d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
192e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
192f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
19300 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
19310 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
19320 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19330 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
19340 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
19350 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
19360 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
19370 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
19380 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19390 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
193a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
193b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
193c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
193d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
193e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
193f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
19400 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
19410 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
19420 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
19430 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
19440 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
19450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
19460 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19470 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
19480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
19490 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
194a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
194b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
194c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
194d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
194e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
194f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
19500 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19510 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
19520 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
19530 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
19540 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
19550 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
19560 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
19570 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
19580 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
19590 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
195a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
195b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
195c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
195d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
195e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
195f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
19600 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
19610 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
19620 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
19630 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
19640 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
19650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
19660 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
19670 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
19680 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
19690 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
196a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
196b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
196c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
196d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
196e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
196f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19700 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
19710 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19720 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
19730 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
19740 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
19750 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
19760 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
19770 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
19780 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
19790 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
197a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
197b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
197c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
197d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
197e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
197f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
19800 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
19810 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
19820 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
19830 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
19840 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
19850 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
19860 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
19870 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19880 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
19890 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
198a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
198b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
198c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
198d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
198e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
198f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
19900 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
19910 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
19920 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
19930 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
19940 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19950 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a 2a  ENABLE_FKEY]].**
19960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19970 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19990 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
199a0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
199b0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
199c0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
199d0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
199e0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
199f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19a00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19a10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19a30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19a40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
19a50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
19a60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19a70 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
19a80 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
19a90 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
19aa0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
19ab0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
19ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19ae0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19af0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19b00 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19b10 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
19b20 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
19b30 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
19b40 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19b50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19b60 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19b70 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19b80 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19b90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
19ba0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19bb0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19bc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19bd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19be0 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20 3c  E_TRIGGER]].** <
19bf0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19c00 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
19c10 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19c40 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
19c50 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
19c60 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
19c70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
19c80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19c90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
19ca0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
19cb0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
19cc0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
19cd0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
19ce0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
19cf0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
19d00 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
19d10 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
19d20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19d40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19d50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19d60 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19d70 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19d80 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
19d90 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
19da0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
19db0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19dc0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
19dd0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
19de0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19df0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
19e00 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
19e10 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19e20 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19e30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
19e40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 56  BCONFIG_ENABLE_V
19e50 49 45 57 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IEW]].** <dt>SQL
19e60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19e70 42 4c 45 5f 56 49 45 57 3c 2f 64 74 3e 0a 2a 2a  BLE_VIEW</dt>.**
19e80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19e90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19ea0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19eb0 5b 43 52 45 41 54 45 20 56 49 45 57 20 7c 20 76  [CREATE VIEW | v
19ec0 69 65 77 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  iews]..** There 
19ed0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19ee0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19ef0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19f00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19f10 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19f20 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 76 69   0 to disable vi
19f30 65 77 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ews,.** positive
19f40 20 74 6f 20 65 6e 61 62 6c 65 20 76 69 65 77 73   to enable views
19f50 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
19f60 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
19f70 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
19f80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19f90 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19fa0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
19fb0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
19fc0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19fd0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19fe0 68 65 72 20 76 69 65 77 73 20 61 72 65 20 64 69  her views are di
19ff0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a000 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
1a010 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
1a020 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a030 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
1a040 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
1a050 63 68 20 63 61 73 65 20 74 68 65 20 76 69 65 77  ch case the view
1a060 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
1a070 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
1a080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1a090 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a0a0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
1a0b0 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ER]].** <dt>SQLI
1a0c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a0d0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
1a0e0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
1a0f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a100 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
1a110 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
1a120 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
1a130 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
1a140 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
1a150 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
1a160 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
1a170 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
1a180 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
1a190 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a1a0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
1a1b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a1c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1a1d0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1a1e0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
1a1f0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
1a200 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
1a210 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
1a220 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
1a230 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a240 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
1a250 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1a260 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1a270 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1a280 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
1a290 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1a2a0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a2b0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
1a2c0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1a2d0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1a2e0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1a2f0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
1a300 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1a310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1a320 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
1a330 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
1a340 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
1a350 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
1a360 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1a370 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
1a380 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a  D_EXTENSION]].**
1a390 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1a3a0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
1a3b0 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
1a3c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
1a3d0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
1a3e0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
1a3f0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1a400 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a410 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
1a420 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
1a430 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
1a440 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
1a450 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
1a460 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1a470 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
1a480 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1a490 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
1a4a0 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
1a4b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a4c0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
1a4d0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
1a4e0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
1a4f0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
1a500 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
1a510 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
1a520 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1a530 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
1a540 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
1a550 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
1a560 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
1a570 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a580 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
1a590 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
1a5a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
1a5b0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a5c0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
1a5d0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
1a5e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1a5f0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
1a600 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a610 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
1a620 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
1a630 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
1a640 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
1a650 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
1a660 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
1a670 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a680 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a690 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a6a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a6b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a6c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a6d0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
1a6e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
1a6f0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
1a700 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1a710 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a720 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a730 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
1a740 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
1a750 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
1a760 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1a770 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a780 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
1a790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a7a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a7b0 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  BNAME]] <dt>SQLI
1a7c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a7d0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
1a7e0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a7f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
1a800 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
1a810 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
1a820 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
1a830 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
1a840 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1a850 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
1a860 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
1a870 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
1a880 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
1a890 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
1a8a0 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
1a8b0 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
1a8c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
1a8d0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
1a8e0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
1a8f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
1a900 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
1a910 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
1a920 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
1a930 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
1a940 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
1a950 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
1a960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a970 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
1a980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1a990 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a9a0 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20  CKPT_ON_CLOSE]] 
1a9b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a9c0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a9d0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
1a9e0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
1a9f0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
1aa00 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
1aa10 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
1aa20 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
1aa30 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
1aa40 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
1aa50 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
1aa60 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
1aa70 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
1aa80 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
1aa90 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
1aaa0 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
1aab0 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
1aac0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
1aad0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
1aae0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
1aaf0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
1ab00 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
1ab10 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
1ab20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ab30 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1ab40 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
1ab50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
1ab60 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
1ab70 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
1ab80 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
1ab90 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
1aba0 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
1abb0 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
1abc0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1abd0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
1abe0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1abf0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1ac00 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1ac10 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
1ac20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1ac30 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1ac40 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
1ac50 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
1ac60 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
1ac70 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
1ac80 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1ac90 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
1aca0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1acb0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1acc0 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74  NABLE_QPSG]] <dt
1acd0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1ace0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
1acf0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
1ad00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1ad10 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
1ad20 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1ad30 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1ad40 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
1ad50 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
1ad60 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
1ad70 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
1ad80 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
1ad90 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
1ada0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
1adb0 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1adc0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
1add0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
1ade0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
1adf0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
1ae00 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
1ae10 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
1ae20 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
1ae30 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
1ae40 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
1ae50 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
1ae60 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
1ae70 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
1ae80 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
1ae90 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
1aea0 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
1aeb0 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
1aec0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
1aed0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
1aee0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1aef0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
1af00 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
1af10 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
1af20 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
1af30 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
1af40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1af50 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
1af60 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
1af70 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
1af80 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
1af90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1afa0 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
1afb0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1afc0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1afd0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
1afe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1aff0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1b000 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1b010 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
1b020 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1b030 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
1b040 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
1b050 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1b060 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1b070 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
1b080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1b090 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1b0a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b0b0 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1b0c0 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1b0d0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1b0e0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1b0f0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1b100 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1b110 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1b120 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1b130 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1b140 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1b150 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1b160 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1b170 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1b180 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1b190 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1b1a0 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1b1b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b1c0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1b1d0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1b1e0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1b1f0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1b200 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1b210 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1b220 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1b230 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1b240 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1b250 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1b260 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1b270 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1b280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1b290 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1b2a0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1b2b0 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1b2c0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1b2d0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1b2e0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1b2f0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1b300 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1b310 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1b320 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1b330 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1b340 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d  _RESET_DATABASE]
1b350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1b360 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1b370 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  BASE</dt>.** <dd
1b380 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45  > Set the SQLITE
1b390 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1b3a0 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e  DATABASE flag an
1b3b0 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56  d then run.** [V
1b3c0 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20  ACUUM] in order 
1b3d0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62  to reset a datab
1b3e0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65  ase back to an e
1b3f0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mpty database.**
1b400 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20   with no schema 
1b410 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20  and no content. 
1b420 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  The following pr
1b430 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e  ocess works even
1b440 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20   for.** a badly 
1b450 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61  corrupted databa
1b460 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e  se file:.** <ol>
1b470 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20  .** <li> If the 
1b480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b490 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65  ion is newly ope
1b4a0 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69  ned, make sure i
1b4b0 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a  t has read the.*
1b4c0 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20  *      database 
1b4d0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72  schema by prepar
1b4e0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64  ing then discard
1b4f0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61  ing some query a
1b500 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20  gainst the.**   
1b510 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20     database, or 
1b520 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
1b530 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1b540 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e  adata(), ignorin
1b550 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72  g any.**      er
1b560 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70  rors.  This step
1b570 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61   is only necessa
1b580 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ry if the applic
1b590 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f  ation desires to
1b5a0 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68   keep.**      th
1b5b0 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41  e database in WA
1b5c0 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65  L mode after the
1b5d0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73   reset if it was
1b5e0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66   in WAL mode bef
1b5f0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  ore.**      the 
1b600 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e  reset.  .** <li>
1b610 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1b620 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1b630 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b640 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a  ABASE, 1, 0);.**
1b650 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65   <li> [sqlite3_e
1b660 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55  xec](db, "[VACUU
1b670 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  M]", 0, 0, 0);.*
1b680 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1b690 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1b6a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1b6b0 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20  ET_DATABASE, 0, 
1b6c0 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20  0);.** </ol>.** 
1b6d0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e  Because resettin
1b6e0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  g a database is 
1b6f0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20  destructive and 
1b700 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68  irreversible, th
1b710 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71  e.** process req
1b720 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66  uires the use of
1b730 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50   this obscure AP
1b740 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73  I and multiple s
1b750 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20  teps to help.** 
1b760 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64  ensure that it d
1b770 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62  oes not happen b
1b780 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a  y accident..**.*
1b790 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b7a0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20  FIG_DEFENSIVE]] 
1b7b0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1b7c0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64  FIG_DEFENSIVE</d
1b7d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
1b7e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45  LITE_DBCONFIG_DE
1b7f0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61  FENSIVE option a
1b800 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1b810 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22  tivates the.** "
1b820 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20  defensive" flag 
1b830 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
1b840 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e  onnection.  When
1b850 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a   the defensive.*
1b860 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65  * flag is enable
1b870 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74  d, language feat
1b880 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20  ures that allow 
1b890 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20  ordinary SQL to 
1b8a0 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79  .** deliberately
1b8b0 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74   corrupt the dat
1b8c0 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64  abase file are d
1b8d0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69  isabled.  The di
1b8e0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72  sabled.** featur
1b8f0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61  es include but a
1b900 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74  re not limited t
1b910 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  o the following:
1b920 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1b930 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69   The [PRAGMA wri
1b940 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d  table_schema=ON]
1b950 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c   statement..** <
1b960 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20  li> The [PRAGMA 
1b970 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 4f 46 46  journal_mode=OFF
1b980 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
1b990 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74  <li> Writes to t
1b9a0 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67  he [sqlite_dbpag
1b9b0 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e] virtual table
1b9c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74  ..** <li> Direct
1b9d0 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64   writes to [shad
1b9e0 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c  ow tables]..** <
1b9f0 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
1ba00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1ba10 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53  ONFIG_WRITABLE_S
1ba20 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49  CHEMA]] <dt>SQLI
1ba30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54  TE_DBCONFIG_WRIT
1ba40 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e  ABLE_SCHEMA</dt>
1ba50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
1ba60 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54  TE_DBCONFIG_WRIT
1ba70 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69  ABLE_SCHEMA opti
1ba80 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
1ba90 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a  deactivates the.
1baa0 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68  ** "writable_sch
1bab0 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20  ema" flag. This 
1bac0 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
1bad0 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63  ect and is logic
1bae0 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a  ally equivalent.
1baf0 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50  ** to setting [P
1bb00 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73  RAGMA writable_s
1bb10 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52  chema=ON] or [PR
1bb20 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63  AGMA writable_sc
1bb30 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68  hema=OFF]..** Th
1bb40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1bb50 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67   to this setting
1bb60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1bb70 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1bb80 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69  able .** the wri
1bb90 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f  table_schema, po
1bba0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1bbb0 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
1bbc0 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  , or negative to
1bbd0 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65  .** leave the se
1bbe0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
1bbf0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1bc00 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1bc10 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65  er to an.** inte
1bc20 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69  ger into which i
1bc30 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1bc40 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1bc50 74 68 65 72 20 74 68 65 20 77 72 69 74 61 62 6c  ther the writabl
1bc60 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65  e_schema.** is e
1bc70 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1bc80 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ed following thi
1bc90 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e  s call..** </dd>
1bca0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1bcb0 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f  DBCONFIG_LEGACY_
1bcc0 41 4c 54 45 52 5f 54 41 42 4c 45 5d 5d 0a 2a 2a  ALTER_TABLE]].**
1bcd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1bce0 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45  NFIG_LEGACY_ALTE
1bcf0 52 5f 54 41 42 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  R_TABLE</dt>.** 
1bd00 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44  <dd>The SQLITE_D
1bd10 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41  BCONFIG_LEGACY_A
1bd20 4c 54 45 52 5f 54 41 42 4c 45 20 6f 70 74 69 6f  LTER_TABLE optio
1bd30 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1bd40 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1bd50 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1bd60 72 20 6f 66 20 74 68 65 20 5b 41 4c 54 45 52 20  r of the [ALTER 
1bd70 54 41 42 4c 45 20 52 45 4e 41 4d 45 5d 20 63 6f  TABLE RENAME] co
1bd80 6d 6d 61 6e 64 20 73 75 63 68 20 69 74 0a 2a 2a  mmand such it.**
1bd90 20 62 65 68 61 76 65 73 20 61 73 20 69 74 20 64   behaves as it d
1bda0 69 64 20 70 72 69 6f 72 20 74 6f 20 5b 76 65 72  id prior to [ver
1bdb0 73 69 6f 6e 20 33 2e 32 34 2e 30 5d 20 28 32 30  sion 3.24.0] (20
1bdc0 31 38 2d 30 36 2d 30 34 29 2e 20 20 53 65 65 20  18-06-04).  See 
1bdd0 74 68 65 0a 2a 2a 20 22 43 6f 6d 70 61 74 69 62  the.** "Compatib
1bde0 69 6c 69 74 79 20 4e 6f 74 69 63 65 22 20 6f 6e  ility Notice" on
1bdf0 20 74 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c   the [ALTER TABL
1be00 45 20 52 45 4e 41 4d 45 20 64 6f 63 75 6d 65 6e  E RENAME documen
1be10 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61  tation] for.** a
1be20 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1be30 61 74 69 6f 6e 2e 20 54 68 69 73 20 66 65 61 74  ation. This feat
1be40 75 72 65 20 63 61 6e 20 61 6c 73 6f 20 62 65 20  ure can also be 
1be50 74 75 72 6e 65 64 20 6f 6e 20 61 6e 64 20 6f 66  turned on and of
1be60 66 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  f.** using the [
1be70 50 52 41 47 4d 41 20 6c 65 67 61 63 79 5f 61 6c  PRAGMA legacy_al
1be80 74 65 72 5f 74 61 62 6c 65 5d 20 73 74 61 74 65  ter_table] state
1be90 6d 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ment..** </dd>.*
1bea0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1beb0 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 5d 5d  CONFIG_DQS_DML]]
1bec0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1bed0 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 3c  BCONFIG_DQS_DML<
1bee0 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /td>.** <dd>The 
1bef0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1bf00 44 51 53 5f 44 4d 4c 20 6f 70 74 69 6f 6e 20 61  DQS_DML option a
1bf10 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1bf20 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c  tivates.** the l
1bf30 65 67 61 63 79 20 5b 64 6f 75 62 6c 65 2d 71 75  egacy [double-qu
1bf40 6f 74 65 64 20 73 74 72 69 6e 67 20 6c 69 74 65  oted string lite
1bf50 72 61 6c 5d 20 6d 69 73 66 65 61 74 75 72 65 20  ral] misfeature 
1bf60 66 6f 72 20 44 4d 4c 20 73 74 61 74 65 6d 65 6e  for DML statemen
1bf70 74 0a 2a 2a 20 6f 6e 6c 79 2c 20 74 68 61 74 20  t.** only, that 
1bf80 69 73 20 44 45 4c 45 54 45 2c 20 49 4e 53 45 52  is DELETE, INSER
1bf90 54 2c 20 53 45 4c 45 43 54 2c 20 61 6e 64 20 55  T, SELECT, and U
1bfa0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 73  PDATE statements
1bfb0 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  . The.** default
1bfc0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 73   value of this s
1bfd0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
1bfe0 69 6e 65 64 20 62 79 20 74 68 65 20 5b 2d 44 53  ined by the [-DS
1bff0 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a 20 63 6f  QLITE_DQS].** co
1c000 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1c010 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  n..** </dd>.**.*
1c020 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1c030 46 49 47 5f 44 51 53 5f 44 44 4c 5d 5d 0a 2a 2a  FIG_DQS_DDL]].**
1c040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1c050 4e 46 49 47 5f 44 51 53 5f 44 44 4c 3c 2f 74 64  NFIG_DQS_DDL</td
1c060 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1c070 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53  ITE_DBCONFIG_DQS
1c080 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
1c090 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
1c0a0 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 5b  .** the legacy [
1c0b0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20 73 74  double-quoted st
1c0c0 72 69 6e 67 20 6c 69 74 65 72 61 6c 5d 20 6d 69  ring literal] mi
1c0d0 73 66 65 61 74 75 72 65 20 66 6f 72 20 44 44 4c  sfeature for DDL
1c0e0 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20   statements,.** 
1c0f0 73 75 63 68 20 61 73 20 43 52 45 41 54 45 20 54  such as CREATE T
1c100 41 42 4c 45 20 61 6e 64 20 43 52 45 41 54 45 20  ABLE and CREATE 
1c110 49 4e 44 45 58 2e 20 54 68 65 0a 2a 2a 20 64 65  INDEX. The.** de
1c120 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74  fault value of t
1c130 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 64  his setting is d
1c140 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
1c150 20 5b 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d 0a   [-DSQLITE_DQS].
1c160 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
1c170 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e  option..** </dd>
1c180 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1c190 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1c1a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20  NFIG_MAINDBNAME 
1c1b0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20             1000 
1c1c0 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a  /* const char* *
1c1d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c1e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
1c1f0 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IDE             
1c200 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  1001 /* void* in
1c210 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
1c220 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1c230 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
1c240 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69         1002 /* i
1c250 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1c260 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1c270 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
1c280 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a  R        1003 /*
1c290 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1c2a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1c2b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
1c2c0 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20  _TOKENIZER 1004 
1c2d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1c2e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1c2f0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
1c300 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30  AD_EXTENSION 100
1c310 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  5 /* int int* */
1c320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c330 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
1c340 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31  _ON_CLOSE      1
1c350 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  006 /* int int* 
1c360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c370 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1c380 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20  E_QPSG          
1c390 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74   1007 /* int int
1c3a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1c3b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49  ITE_DBCONFIG_TRI
1c3c0 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20  GGER_EQP        
1c3d0 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69     1008 /* int i
1c3e0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1c3f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1c400 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 20 20  ESET_DATABASE   
1c410 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74       1009 /* int
1c420 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1c430 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1c440 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 20 20  _DEFENSIVE      
1c450 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69         1010 /* i
1c460 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1c470 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1c480 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45  IG_WRITABLE_SCHE
1c490 4d 41 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a  MA       1011 /*
1c4a0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1c4b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1c4c0 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45  NFIG_LEGACY_ALTE
1c4d0 52 5f 54 41 42 4c 45 20 20 20 20 31 30 31 32 20  R_TABLE    1012 
1c4e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1c4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1c500 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 20 20  CONFIG_DQS_DML  
1c510 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31               101
1c520 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  3 /* int int* */
1c530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c540 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c  DBCONFIG_DQS_DDL
1c550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1c560 30 31 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  014 /* int int* 
1c570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c580 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1c590 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1c5a0 20 31 30 31 35 20 2f 2a 20 69 6e 74 20 69 6e 74   1015 /* int int
1c5b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1c5c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58  ITE_DBCONFIG_MAX
1c5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c5e0 20 20 20 31 30 31 35 20 2f 2a 20 4c 61 72 67 65     1015 /* Large
1c5f0 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a  st DBCONFIG */..
1c600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c610 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
1c620 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
1c630 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
1c640 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c650 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
1c660 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
1c670 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
1c680 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
1c690 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
1c6a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1c6b0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
1c6c0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
1c6d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
1c6e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
1c6f0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
1c700 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
1c710 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
1c720 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1c730 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
1c740 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
1c750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c760 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
1c770 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
1c780 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c790 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
1c7a0 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
1c7b0 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
1c7c0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1c7d0 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
1c7e0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
1c7f0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
1c800 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
1c810 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
1c820 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
1c830 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
1c840 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
1c850 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
1c860 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
1c870 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
1c880 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
1c890 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
1c8a0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
1c8b0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
1c8c0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
1c8d0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
1c8e0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
1c8f0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
1c900 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
1c910 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
1c920 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
1c930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1c940 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1c950 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
1c960 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74  face usually ret
1c970 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
1c980 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20   of.** the most 
1c990 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
1c9a0 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
1c9b0 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
1c9c0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
1c9d0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
1c9e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49  connection D. ^I
1c9f0 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
1ca00 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
1ca10 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  es are not.** re
1ca20 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73  corded. ^If no s
1ca30 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1ca40 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
1ca50 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20  ables have ever 
1ca60 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20  occurred .** on 
1ca70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ca80 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20  nection D, then 
1ca90 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1caa0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
1cab0 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a  urns .** zero..*
1cac0 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20  *.** As well as 
1cad0 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61  being set automa
1cae0 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20  tically as rows 
1caf0 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74  are inserted int
1cb00 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  o database.** ta
1cb10 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  bles, the value 
1cb20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
1cb30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1cb40 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20   set explicitly 
1cb50 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
1cb60 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1cb70 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f  owid()].**.** So
1cb80 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  me virtual table
1cb90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1cba0 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73   may INSERT rows
1cbb0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
1cbc0 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  es as.** part of
1cbd0 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72   committing a tr
1cbe0 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20  ansaction (e.g. 
1cbf0 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63  to flush data ac
1cc00 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d  cumulated in mem
1cc10 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e  ory.** to disk).
1cc20 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75   In this case su
1cc30 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1cc40 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1cc50 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64  return the rowid
1cc60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1cc70 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e  ith these intern
1cc80 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74  al INSERT operat
1cc90 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64  ions, which lead
1cca0 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69  s to .** unintui
1ccb0 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69  tive results. Vi
1ccc0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1ccd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74  ementations that
1cce0 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77   do write to row
1ccf0 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20  id.** tables in 
1cd00 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f  this way can avo
1cd10 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20  id this problem 
1cd20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65  by restoring the
1cd30 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f   original .** ro
1cd40 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20  wid value using 
1cd50 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1cd60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1cd70 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  ] before returni
1cd80 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74  ng .** control t
1cd90 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a  o the user..**.*
1cda0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
1cdb0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
1cdc0 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20   a trigger then 
1cdd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
1cde0 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  l .** return the
1cdf0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
1ce00 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20  inserted row as 
1ce10 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1ce20 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69  ger is .** runni
1ce30 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69  ng. Once the tri
1ce40 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64  gger program end
1ce50 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1ce60 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
1ce70 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
1ce80 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
1ce90 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
1cea0 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e  ger was fired.)^
1ceb0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
1cec0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
1ced0 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
1cee0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
1cef0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
1cf00 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
1cf10 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
1cf20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1cf30 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
1cf40 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
1cf50 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
1cf60 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
1cf70 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
1cf80 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
1cf90 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
1cfa0 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
1cfb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1cfc0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
1cfd0 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
1cfe0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
1cff0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
1d000 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
1d010 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
1d020 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
1d030 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
1d040 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
1d050 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
1d060 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
1d070 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
1d080 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
1d090 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
1d0a0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
1d0b0 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
1d0c0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
1d0d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1d0e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
1d0f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
1d100 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1d110 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
1d120 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
1d130 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
1d140 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
1d150 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
1d160 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
1d170 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
1d180 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
1d190 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
1d1a0 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
1d1b0 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
1d1c0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
1d1d0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1d1e0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1d1f0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
1d200 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
1d210 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
1d220 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1d230 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
1d240 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1d250 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
1d260 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
1d270 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
1d280 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1d290 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
1d2a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1d2b0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
1d2c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1d2d0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
1d2e0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
1d2f0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
1d300 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
1d310 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
1d320 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
1d330 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1d340 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1d350 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
1d360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d370 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e   Set the Last In
1d380 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65  sert Rowid value
1d390 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  ..** METHOD: sql
1d3a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
1d3b0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1d3c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20  insert_rowid(D, 
1d3d0 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73  R) method allows
1d3e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d3f0 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76   to.** set the v
1d400 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d410 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
1d420 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1d430 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77  id(D) to R .** w
1d440 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67  ithout inserting
1d450 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20   a row into the 
1d460 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69  database..*/.voi
1d470 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  d sqlite3_set_la
1d480 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1d490 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33  sqlite3*,sqlite3
1d4a0 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
1d4b0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
1d4c0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
1d4d0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1d4e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1d4f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1d500 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1d510 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1d520 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
1d530 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1d540 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1d550 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
1d560 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1d570 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
1d580 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61  ment on the data
1d590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d5a0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1d5b0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e   only parameter.
1d5c0 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61  .** ^Executing a
1d5d0 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1d5e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
1d5f0 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  oes not modify t
1d600 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1d610 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1d620 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ction..**.** ^On
1d630 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1d640 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  directly by the 
1d650 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1d660 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1d670 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  nt are.** consid
1d680 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79  ered - auxiliary
1d690 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
1d6a0 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  by [CREATE TRIGG
1d6b0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20  ER | triggers], 
1d6c0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1d6d0 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45   actions] or [RE
1d6e0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
1d6f0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1d700 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1d710 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20   .** Changes to 
1d720 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1d730 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a  intercepted by .
1d740 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  ** [INSTEAD OF t
1d750 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44  rigger | INSTEAD
1d760 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72   OF triggers] ar
1d770 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e  e not counted. ^
1d780 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65  The value .** re
1d790 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d7a0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65  3_changes() imme
1d7b0 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e  diately after an
1d7c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1d7d0 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74  or .** DELETE st
1d7e0 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61  atement run on a
1d7f0 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20   view is always 
1d800 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67  zero. Only chang
1d810 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20  es made to real 
1d820 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63  .** tables are c
1d830 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
1d840 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f  ings are more co
1d850 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65  mplicated if the
1d860 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1d870 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  () function is.*
1d880 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65  * executed while
1d890 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1d8a0 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54  am is running. T
1d8b0 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69  his may happen i
1d8c0 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  f the.** program
1d8d0 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67   uses the [chang
1d8e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1d8f0 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f  n], or if some o
1d900 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ther callback.**
1d910 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65   function invoke
1d920 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  s sqlite3_change
1d930 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73  s() directly. Es
1d940 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a  sentially:.** .*
1d950 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
1d960 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69   ^(Before enteri
1d970 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  ng a trigger pro
1d980 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72  gram the value r
1d990 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1d9a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61       sqlite3_cha
1d9b0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1d9c0 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20  is saved. After 
1d9d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1d9e0 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68  ram .**        h
1d9f0 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65  as finished, the
1da00 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20   original value 
1da10 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a  is restored.)^.*
1da20 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57  * .**   <li> ^(W
1da30 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1da40 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53  program each INS
1da50 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20  ERT, UPDATE and 
1da60 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20  DELETE .**      
1da70 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73    statement sets
1da80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1da90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1daa0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1dab0 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74      upon complet
1dac0 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f  ion as normal. O
1dad0 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76  f course, this v
1dae0 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e  alue will not in
1daf0 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20  clude .**       
1db00 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72   any changes per
1db10 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72  formed by sub-tr
1db20 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73  iggers, as the s
1db30 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1db40 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75   .**        valu
1db50 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20  e will be saved 
1db60 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74  and restored aft
1db70 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67  er each sub-trig
1db80 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a  ger has run.)^.*
1db90 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e  * </ul>.** .** ^
1dba0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
1dbb0 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29  if the changes()
1dbc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f   SQL function (o
1dbd0 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73  r similar) is us
1dbe0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
1dbf0 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  st INSERT, UPDAT
1dc00 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1dc10 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1dc20 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72  rigger, it .** r
1dc30 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
1dc40 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   as set when the
1dc50 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65   calling stateme
1dc60 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69  nt began executi
1dc70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ng..** ^If it is
1dc80 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63   used by the sec
1dc90 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ond or subsequen
1dca0 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74  t such statement
1dcb0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1dcc0 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74  r .** program, t
1dcd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1dce0 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e  d reflects the n
1dcf0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
1dd00 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  dified by the .*
1dd10 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52  * previous INSER
1dd20 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1dd30 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1dd40 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
1dd50 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  igger..**.** If 
1dd60 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1dd70 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1dd80 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1dd90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1dda0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1ddb0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
1ddc0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1ddd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1dde0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
1ddf0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1de00 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  ingful..**.** Se
1de10 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a  e also:.** <ul>.
1de20 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c  ** <li> the [sql
1de30 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1de40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  es()] interface.
1de50 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75  ** <li> the [cou
1de60 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1de70 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1de80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1de90 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20  nction].** <li> 
1dea0 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f  the [data_versio
1deb0 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75  n pragma].** </u
1dec0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
1ded0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1dee0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1def0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1df00 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1df10 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1df20 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1df30 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1df40 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1df50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1df60 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1df70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1df80 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1df90 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1dfa0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1dfb0 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1dfc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1dfd0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1dfe0 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1dff0 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1e000 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1e010 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1e020 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1e030 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1e040 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1e050 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1e060 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1e070 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1e080 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1e090 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1e0a0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1e0b0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1e0c0 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1e0d0 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1e0e0 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1e0f0 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1e100 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1e110 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1e120 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1e130 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1e140 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1e150 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1e160 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1e170 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
1e180 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1e190 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74  _changes(D)] int
1e1a0 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1e1b0 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rts the number.*
1e1c0 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63  * of rows that c
1e1d0 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51  hanged due to SQ
1e1e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  L statement run 
1e1f0 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65  against database
1e200 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
1e210 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62  .  Any changes b
1e220 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  y other database
1e230 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65   connections are
1e240 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20   ignored..** To 
1e250 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61  detect changes a
1e260 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73  gainst a databas
1e270 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65  e file from othe
1e280 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
1e290 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68  nnections use th
1e2a0 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76  e [PRAGMA data_v
1e2b0 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20  ersion] command 
1e2c0 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  or the.** [SQLIT
1e2d0 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52  E_FCNTL_DATA_VER
1e2e0 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74  SION] [file cont
1e2f0 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rol]..** .** If 
1e300 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1e310 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1e320 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1e330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1e340 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1e350 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1e360 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1e370 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1e380 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1e390 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1e3a0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a  t meaningful..**
1e3b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a  .** See also:.**
1e3c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68   <ul>.** <li> th
1e3d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1e3e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  es()] interface.
1e3f0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75  ** <li> the [cou
1e400 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1e410 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1e420 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1e430 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20  nction].** <li> 
1e440 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f  the [data_versio
1e450 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  n pragma].** <li
1e460 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  > the [SQLITE_FC
1e470 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
1e480 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d  ] [file control]
1e490 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
1e4a0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1e4b0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1e4c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e4d0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1e4e0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1e4f0 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1e500 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1e510 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1e520 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1e530 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1e540 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1e550 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1e560 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1e570 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1e580 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1e590 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1e5a0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1e5b0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1e5c0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1e5d0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1e5e0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1e5f0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1e600 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1e610 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1e620 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1e630 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1e640 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1e650 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1e660 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1e670 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1e680 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1e690 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1e6a0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1e6b0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1e6c0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1e6d0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1e6e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1e6f0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1e700 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1e710 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1e720 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1e730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1e740 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1e750 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1e760 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1e770 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1e780 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1e790 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1e7a0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1e7b0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1e7c0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1e7d0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1e7e0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1e7f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1e800 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1e810 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1e820 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1e830 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1e840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1e850 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1e860 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1e870 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1e880 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1e890 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1e8a0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1e8b0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1e8c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1e8d0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1e8e0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1e8f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1e900 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e910 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1e920 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1e930 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1e940 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1e950 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1e960 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1e970 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1e980 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1e990 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1e9a0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1e9b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e9c0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1e9d0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1e9e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1e9f0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1ea00 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1ea10 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1ea20 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1ea30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1ea40 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1ea50 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1ea60 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1ea70 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1ea80 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1ea90 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1eaa0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1eab0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1eac0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1ead0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1eae0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1eaf0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1eb00 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1eb10 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1eb20 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1eb30 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1eb40 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1eb50 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1eb60 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1eb70 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1eb80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1eb90 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1eba0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1ebb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1ebc0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1ebd0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1ebe0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1ebf0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1ec00 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1ec10 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1ec20 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1ec30 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1ec40 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1ec50 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1ec60 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1ec70 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1ec80 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1ec90 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1eca0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1ecb0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1ecc0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1ecd0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1ece0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1ecf0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1ed00 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1ed10 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1ed20 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1ed30 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1ed40 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1ed50 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1ed60 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1ed70 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1ed80 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1ed90 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1eda0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1edb0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1edc0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1edd0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1ede0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1edf0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1ee00 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1ee10 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1ee20 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1ee30 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1ee40 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1ee50 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1ee60 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1ee70 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1ee80 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1ee90 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1eea0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1eeb0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1eec0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1eed0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1eee0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1eef0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1ef00 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1ef10 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1ef20 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1ef30 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1ef40 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1ef50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1ef60 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1ef70 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1ef80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1ef90 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1efa0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1efb0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1efc0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1efd0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1efe0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1eff0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1f000 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1f010 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1f020 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1f030 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1f040 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1f050 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1f060 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1f070 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1f080 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1f090 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1f0a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1f0b0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1f0c0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1f0d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1f0e0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1f0f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1f100 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1f110 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1f120 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1f130 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1f140 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1f150 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1f160 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1f170 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1f180 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1f190 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1f1a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1f1b0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1f1c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1f1d0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1f1e0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1f1f0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1f200 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1f210 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f220 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1f230 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1f240 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1f250 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1f260 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1f270 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1f280 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1f290 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1f2a0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1f2b0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1f2c0 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1f2d0 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1f2e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1f2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f300 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1f310 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1f320 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1f330 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1f340 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1f350 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1f360 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1f370 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1f380 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1f390 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1f3a0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1f3b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f3c0 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1f3d0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1f3e0 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1f3f0 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1f400 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1f410 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1f420 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1f430 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1f440 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1f450 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1f460 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1f470 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1f480 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1f490 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1f4a0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1f4b0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1f4c0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1f4d0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1f4e0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1f4f0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1f500 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1f510 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1f520 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1f530 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1f540 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1f550 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1f560 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1f570 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1f580 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1f590 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1f5a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1f5b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1f5c0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1f5d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1f5e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1f5f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1f600 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1f610 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1f620 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1f630 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1f640 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1f650 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1f660 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1f670 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1f680 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1f690 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1f6a0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1f6b0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1f6c0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1f6d0 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1f6e0 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1f6f0 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1f700 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1f710 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1f720 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1f730 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1f740 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1f750 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1f760 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1f770 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1f780 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1f790 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1f7a0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1f7b0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1f7c0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1f7d0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1f7e0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1f7f0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1f800 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1f810 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1f820 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1f830 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1f840 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1f850 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1f860 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1f870 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1f880 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1f890 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1f8a0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1f8b0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1f8c0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1f8d0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1f8e0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1f8f0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1f900 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1f910 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1f920 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1f930 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1f940 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1f950 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1f960 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1f970 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1f980 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1f990 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1f9a0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1f9b0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1f9c0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1f9d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1f9e0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1f9f0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1fa00 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1fa10 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1fa20 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1fa30 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1fa40 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1fa50 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1fa60 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1fa70 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1fa80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1fa90 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1faa0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1fab0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1fac0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1fad0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1fae0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1faf0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1fb00 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1fb10 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1fb20 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1fb30 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1fb40 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1fb50 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1fb60 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1fb70 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1fb80 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1fb90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1fba0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1fbb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1fbc0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1fbd0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1fbe0 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1fbf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1fc00 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1fc10 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1fc20 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1fc30 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1fc40 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1fc50 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1fc60 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1fc70 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1fc80 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1fc90 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1fca0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1fcb0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1fcc0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1fcd0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1fce0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1fcf0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1fd00 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1fd10 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1fd20 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1fd30 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1fd40 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1fd50 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1fd60 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1fd70 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1fd80 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1fd90 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1fda0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1fdb0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1fdc0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1fdd0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1fde0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1fdf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1fe00 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1fe10 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1fe20 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1fe30 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1fe40 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1fe50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1fe60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1fe70 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1fe80 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1fe90 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1fea0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1feb0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1fec0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1fed0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1fee0 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1fef0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1ff00 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1ff10 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1ff20 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1ff30 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1ff40 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1ff50 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1ff60 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1ff70 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1ff80 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1ff90 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1ffa0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1ffb0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1ffc0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1ffd0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1ffe0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1fff0 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
20000 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
20010 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
20020 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
20030 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
20040 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
20050 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
20060 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
20070 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
20080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20090 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
200a0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
200b0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
200c0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
200d0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
200e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
200f0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
20100 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
20110 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
20120 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
20130 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
20140 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
20150 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
20160 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
20170 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
20180 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
20190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
201a0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
201b0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
201c0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
201d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
201e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
201f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
20200 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
20210 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
20220 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
20230 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
20240 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
20250 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
20260 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
20270 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
20280 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
20290 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
202a0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
202b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
202c0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
202d0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
202e0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
202f0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
20300 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
20310 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
20320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
20330 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
20340 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
20350 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
20360 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
20370 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
20380 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
20390 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
203a0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
203b0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
203c0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
203d0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
203e0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
203f0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
20400 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
20410 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
20420 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
20430 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
20440 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
20450 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
20460 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
20470 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
20480 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
20490 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
204a0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
204b0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
204c0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
204d0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
204e0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
204f0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
20500 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
20510 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
20520 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
20530 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
20540 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
20550 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
20560 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
20570 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
20580 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
20590 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
205a0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
205b0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
205c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
205d0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
205e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
205f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
20600 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
20610 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
20620 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
20630 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
20640 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
20650 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
20660 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
20670 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
20680 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
20690 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
206a0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
206b0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
206c0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
206d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
206e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
206f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
20700 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
20710 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
20720 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
20730 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
20740 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
20750 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
20760 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
20770 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
20780 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
20790 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
207a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
207b0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
207c0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
207d0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
207e0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
207f0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
20800 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
20810 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
20820 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
20830 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
20840 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
20850 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
20860 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
20870 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
20880 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
20890 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
208a0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
208b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
208c0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
208d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
208e0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
208f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
20900 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
20910 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
20920 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
20930 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
20940 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
20950 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
20960 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
20970 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
20980 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
20990 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
209a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
209b0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
209c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
209d0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
209e0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
209f0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
20a00 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
20a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
20a20 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
20a30 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
20a40 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
20a50 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
20a60 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
20a70 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
20a80 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
20a90 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
20aa0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
20ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
20ac0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
20ad0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
20ae0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
20af0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
20b00 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
20b10 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
20b20 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
20b30 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
20b40 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
20b50 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
20b60 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
20b70 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
20b80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20b90 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
20ba0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
20bb0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
20bc0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
20bd0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
20be0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
20bf0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
20c00 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
20c10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
20c20 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
20c30 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
20c40 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
20c50 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
20c60 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
20c70 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
20c80 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
20c90 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
20ca0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
20cb0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
20cc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20cd0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
20ce0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
20cf0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
20d00 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
20d10 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
20d20 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
20d30 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
20d40 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
20d50 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
20d60 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
20d70 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
20d80 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
20d90 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
20da0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
20db0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
20dc0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
20dd0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
20de0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20df0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
20e00 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
20e10 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
20e20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
20e30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20e40 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
20e50 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
20e60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
20e70 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
20e80 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
20e90 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
20ea0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
20eb0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
20ec0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
20ed0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
20ee0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
20ef0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
20f00 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
20f10 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
20f20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
20f30 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
20f40 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
20f50 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
20f60 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
20f70 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
20f80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
20f90 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
20fa0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
20fb0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
20fc0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
20fd0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
20fe0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20ff0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
21000 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
21010 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
21020 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
21030 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
21040 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
21050 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
21060 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
21070 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74  e common formatt
21080 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
21090 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
210a0 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66 28   library printf(
210b0 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  ) .** plus some 
210c0 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
210d0 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 20  tandard formats 
210e0 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77  ([%q], [%Q], [%w
210f0 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a  ], and [%z])..**
21100 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74 2d   See the [built-
21110 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f 63  in printf()] doc
21120 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 64  umentation for d
21130 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  etails..**.** ^T
21140 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
21150 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
21160 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
21170 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
21180 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
21190 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
211a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
211b0 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20 54  alloc64()]..** T
211c0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
211d0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
211e0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
211f0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
21200 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
21210 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
21220 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
21230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
21240 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
21250 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  64()] is unable 
21260 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
21270 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
21280 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
21290 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
212a0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
212b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
212c0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
212d0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
212e0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
212f0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
21300 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
21310 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
21320 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
21330 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
21340 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
21350 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
21360 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
21370 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
21380 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
21390 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
213a0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
213b0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
213c0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
213d0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
213e0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
213f0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
21400 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
21410 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
21420 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
21430 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
21440 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
21450 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
21460 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
21470 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
21480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
21490 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
214a0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
214b0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
214c0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
214d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
214e0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
214f0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
21500 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
21510 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
21520 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
21530 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
21540 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
21550 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
21560 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
21570 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
21580 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
21590 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
215a0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
215b0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
215c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
215d0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
215e0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
215f0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
21600 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
21610 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
21620 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
21630 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
21640 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
21650 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
21660 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
21670 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
21680 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
21690 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
216a0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
216b0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
216c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
216d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
216e0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
216f0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
21700 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
21710 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21720 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  :  [built-in pri
21730 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66 28  ntf()], [printf(
21740 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
21750 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
21760 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
21770 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
21780 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
21790 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
217a0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
217b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
217c0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
217d0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
217e0 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
217f0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
21800 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
21810 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
21820 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
21830 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
21840 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
21850 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
21860 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
21870 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
21880 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
21890 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
218a0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
218b0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
218c0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
218d0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
218e0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
218f0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
21900 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
21910 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
21920 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
21930 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
21940 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
21950 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
21960 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21970 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
21980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
21990 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
219a0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
219b0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
219c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
219d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
219e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
219f0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
21a00 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
21a10 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
21a20 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
21a30 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
21a40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
21a50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
21a60 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
21a70 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
21a80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21a90 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
21aa0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
21ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
21ac0 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
21ad0 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
21ae0 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
21af0 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
21b00 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
21b10 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
21b20 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
21b30 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
21b40 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
21b50 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
21b60 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
21b70 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
21b80 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
21b90 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
21ba0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
21bb0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
21bc0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
21bd0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
21be0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
21bf0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
21c00 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
21c10 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
21c20 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
21c30 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
21c40 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
21c50 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
21c60 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
21c70 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
21c80 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
21c90 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
21ca0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
21cb0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
21cc0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
21cd0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
21ce0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
21cf0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
21d00 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
21d10 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
21d20 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
21d30 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
21d40 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
21d50 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
21d60 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
21d70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
21d80 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
21d90 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
21da0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
21db0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
21dc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
21dd0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
21de0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
21df0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21e00 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
21e10 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
21e20 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
21e30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21e40 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
21e50 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
21e60 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
21e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
21e80 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
21e90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
21ea0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
21eb0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
21ec0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
21ed0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
21ee0 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
21ef0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21f00 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
21f10 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
21f20 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
21f30 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
21f40 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
21f50 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
21f60 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
21f70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21f80 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
21f90 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
21fa0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
21fb0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
21fc0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
21fd0 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
21fe0 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
21ff0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
22000 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
22010 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
22020 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
22030 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
22040 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
22050 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
22060 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
22070 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
22080 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
22090 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
220a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
220b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
220c0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
220d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
220e0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
220f0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
22100 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
22110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
22120 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
22130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
22140 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
22150 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
22160 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
22170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
22180 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
22190 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
221a0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
221b0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
221c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
221d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
221e0 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
221f0 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
22200 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
22210 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
22220 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
22230 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
22240 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
22250 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
22260 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
22270 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
22280 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
22290 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
222a0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
222b0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
222c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
222d0 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
222e0 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
222f0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
22300 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
22310 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
22320 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
22330 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
22340 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
22350 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
22360 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
22370 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
22380 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
22390 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
223a0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
223b0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
223c0 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
223d0 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
223e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
223f0 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
22400 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
22410 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
22420 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
22430 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
22440 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
22450 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
22460 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
22470 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
22480 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
22490 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
224a0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
224b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
224c0 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
224d0 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
224e0 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
224f0 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
22500 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
22510 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
22520 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
22530 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
22540 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
22550 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
22560 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
22570 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
22580 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
22590 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
225a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
225b0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
225c0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
225d0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
225e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
225f0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
22600 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
22610 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
22620 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
22630 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
22640 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
22650 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
22660 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
22670 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
22680 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
22690 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
226a0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
226b0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
226c0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
226d0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
226e0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
226f0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
22700 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
22710 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
22720 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
22730 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
22740 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
22750 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
22760 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
22770 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
22780 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
22790 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
227a0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
227b0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
227c0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
227d0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
227e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
227f0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
22800 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
22810 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
22820 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
22830 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
22840 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
22850 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
22860 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
22870 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
22880 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
22890 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
228a0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
228b0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
228c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
228d0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
228e0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
228f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
22900 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
22910 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
22920 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
22930 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
22940 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
22950 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
22960 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
22970 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
22980 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
22990 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
229a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
229b0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
229c0 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
229d0 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
229e0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
229f0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
22a00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
22a10 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
22a20 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
22a30 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
22a40 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
22a50 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
22a60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
22a70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
22a80 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
22a90 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
22aa0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
22ab0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
22ac0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
22ad0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
22ae0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
22af0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
22b00 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
22b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
22b20 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
22b30 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
22b40 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
22b50 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
22b60 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
22b70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
22b80 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
22b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
22ba0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
22bb0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
22bc0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
22bd0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
22be0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
22bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
22c00 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
22c10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
22c20 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
22c30 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
22c40 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
22c50 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
22c60 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
22c70 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
22c80 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
22c90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
22ca0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
22cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
22cc0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
22cd0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
22ce0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
22cf0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
22d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
22d10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
22d20 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
22d30 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
22d40 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
22d50 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
22d60 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
22d70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
22d80 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
22d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
22da0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
22db0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
22dc0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
22dd0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
22de0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
22df0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
22e00 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
22e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
22e20 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
22e30 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
22e40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
22e50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
22e60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
22e70 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
22e80 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
22e90 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
22ea0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
22eb0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
22ec0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
22ed0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
22ee0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
22ef0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
22f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22f10 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
22f20 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
22f30 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
22f40 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
22f50 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
22f60 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
22f70 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
22f80 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
22f90 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
22fa0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
22fb0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
22fc0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
22fd0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
22fe0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
22ff0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
23000 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
23010 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
23020 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
23030 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
23040 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
23050 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
23060 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
23070 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
23080 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
23090 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
230a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
230b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
230c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
230d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
230e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
230f0 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
23100 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
23110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
23120 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
23130 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
23140 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
23150 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
23160 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
23170 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
23180 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
23190 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
231a0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
231b0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
231c0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
231d0 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
231e0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
231f0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
23200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
23210 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
23220 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
23230 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
23240 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
23250 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
23260 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
23270 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
23280 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
23290 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
232a0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
232b0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
232c0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
232d0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
232e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
232f0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
23300 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
23310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
23320 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
23330 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
23340 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
23350 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ite3.** KEYWORDS
23360 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  : {authorizer ca
23370 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54  llback}.**.** ^T
23380 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
23390 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
233a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
233b0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
233c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
233d0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
233e0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
233f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
23400 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
23410 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23420 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
23430 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
23440 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
23450 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
23460 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
23470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23480 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
23490 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
234a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
234b0 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  re16()], [sqlite
234c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
234d0 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
234e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
234f0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
23500 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
23510 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
23520 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
23530 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
23540 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
23550 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
23560 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
23570 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
23580 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
23590 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
235a0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
235b0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
235c0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
235d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
235e0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
235f0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
23600 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
23610 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
23620 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
23630 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
23640 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
23650 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
23660 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
23670 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
23680 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
23690 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
236a0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
236b0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
236c0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
236d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
236e0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
236f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
23700 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
23710 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
23720 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
23730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
23740 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
23750 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
23760 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
23770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
23780 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
23790 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
237a0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
237b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
237c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
237d0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
237e0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
237f0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
23800 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
23810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
23820 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
23830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23840 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
23850 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
23860 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
23870 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
23880 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
23890 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
238a0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
238b0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
238c0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
238d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
238e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
238f0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
23900 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
23910 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
23920 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23930 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
23940 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
23950 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
23960 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
23970 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
23980 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
23990 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
239a0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
239b0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
239c0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
239d0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
239e0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
239f0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
23a00 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65  llback are eithe
23a10 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
23a20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  or zero-terminat
23a30 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68  ed strings.** th
23a40 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
23a50 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
23a60 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
23a70 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
23a80 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
23a90 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
23aa0 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f  prepared to enco
23ab0 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  unter a NULL poi
23ac0 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f  nter in any.** o
23ad0 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f  f the third thro
23ae0 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61  ugh the sixth pa
23af0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
23b00 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
23b10 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49  llback..**.** ^I
23b20 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
23b30 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
23b40 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
23b50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
23b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
23b70 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
23b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23b90 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
23ba0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
23bb0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
23bc0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
23bd0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
23be0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
23bf0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
23c00 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
23c10 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
23c20 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
23c30 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
23c40 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
23c50 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
23c60 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
23c70 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
23c80 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
23c90 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74  le..** ^When a t
23ca0 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63  able is referenc
23cb0 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d  ed by a [SELECT]
23cc0 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76   but no column v
23cd0 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74  alues are.** ext
23ce0 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74  racted from that
23cf0 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d   table (for exam
23d00 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c  ple in a query l
23d10 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63  ike.** "SELECT c
23d20 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62  ount(*) FROM tab
23d30 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c  ") then the [SQL
23d40 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72  ITE_READ] author
23d50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
23d60 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
23d70 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20   for that table 
23d80 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61  with a column na
23d90 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d  me that is an em
23da0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  pty string..** ^
23db0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
23dc0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
23dd0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
23de0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
23df0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
23e00 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
23e10 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
23e20 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
23e30 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
23e40 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
23e50 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
23e60 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
23e70 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
23e80 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
23e90 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
23ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
23eb0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
23ec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
23ed0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
23ee0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
23ef0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
23f00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
23f10 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
23f20 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
23f30 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
23f40 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
23f50 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
23f60 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
23f70 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
23f80 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
23f90 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
23fa0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
23fb0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
23fc0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
23fd0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
23fe0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
23ff0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
24000 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
24010 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
24020 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
24030 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
24040 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
24050 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
24060 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
24070 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
24080 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
24090 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
240a0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
240b0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
240c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
240d0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
240e0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
240f0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
24100 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
24110 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
24120 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
24130 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
24140 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
24150 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
24160 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
24170 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
24180 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
24190 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
241a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
241b0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
241c0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
241d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
241e0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
241f0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
24200 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
24210 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
24220 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
24230 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
24240 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
24250 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
24260 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
24270 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
24280 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
24290 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
242a0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
242b0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
242c0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
242d0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
242e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
242f0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
24300 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
24310 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
24320 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
24330 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
24340 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
24350 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
24360 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
24370 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
24380 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
24390 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
243a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
243b0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
243c0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
243d0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
243e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
243f0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
24400 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
24410 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
24420 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
24430 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24440 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
24450 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
24460 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
24470 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
24480 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
24490 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
244a0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
244b0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
244c0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
244d0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
244e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
244f0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
24500 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
24510 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
24520 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
24530 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
24540 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
24550 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
24560 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24570 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
24580 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24590 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
245a0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
245b0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
245c0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
245d0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
245e0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
245f0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
24600 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
24610 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
24620 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
24630 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
24640 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
24650 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
24660 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
24670 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
24680 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
24690 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
246a0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
246b0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
246c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
246d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
246e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
246f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
24700 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
24710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24720 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
24730 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
24740 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
24750 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
24760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
24770 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
24780 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
24790 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
247a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
247b0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
247c0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
247d0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
247e0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
247f0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
24800 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
24810 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24820 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
24830 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
24840 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
24850 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
24860 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
24870 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
24880 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
24890 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
248a0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
248b0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
248c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
248d0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
248e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
248f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
24900 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
24910 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
24920 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
24930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24940 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
24950 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
24960 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
24970 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
24980 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
24990 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
249a0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
249b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
249c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
249d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
249e0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
249f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
24a00 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
24a10 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
24a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
24a30 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
24a40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
24a50 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
24a60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
24a70 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
24a80 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
24a90 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
24aa0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
24ab0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
24ac0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
24ad0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
24ae0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
24af0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
24b00 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
24b10 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
24b20 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
24b30 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
24b40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
24b50 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
24b60 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
24b70 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
24b80 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
24b90 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
24ba0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
24bb0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
24bc0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
24bd0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
24be0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
24bf0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
24c00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
24c10 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
24c20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
24c30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
24c40 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
24c50 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
24c60 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
24c70 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
24c80 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
24c90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
24ca0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
24cb0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
24cc0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
24cd0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
24ce0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
24cf0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
24d00 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
24d10 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
24d20 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
24d30 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
24d40 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
24d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24d70 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
24d80 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
24d90 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
24da0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
24db0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
24dc0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
24dd0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
24de0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24df0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
24e00 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
24e10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24e20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24e30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24e40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24e50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
24e60 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
24e70 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
24e80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24e90 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24ea0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
24eb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24ec0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24ed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24ee0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
24ef0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
24f00 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
24f10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24f20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24f30 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
24f40 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
24f50 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
24f60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24f80 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
24f90 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
24fa0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
24fb0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24fd0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
24fe0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
24ff0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
25000 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
25020 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
25030 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
25040 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
25050 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
25060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
25070 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
25080 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
25090 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
250a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
250b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
250c0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
250d0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
250e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
250f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
25100 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
25110 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
25120 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
25130 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
25140 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
25150 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
25160 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
25170 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
25180 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
25190 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
251a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
251b0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
251c0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
251d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
251e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
251f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
25200 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
25210 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
25220 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
25230 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
25240 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
25250 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
25260 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
25270 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
25280 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
25290 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
252a0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
252b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
252c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
252d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
252e0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
252f0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
25300 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
25310 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25320 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
25330 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
25340 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
25350 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
25360 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
25370 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
25380 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
25390 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
253a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
253b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
253c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
253d0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
253e0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
253f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25400 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25420 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
25430 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
25440 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
25450 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
25460 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25470 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
25480 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
25490 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
254a0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
254b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
254c0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
254d0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
254e0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
254f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
25510 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
25520 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
25530 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
25540 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
25550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
25560 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
25570 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
25580 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
25590 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
255a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
255b0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
255c0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
255d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
255e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
255f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
25600 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
25610 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
25620 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
25630 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
25640 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
25650 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
25660 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
25670 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
25680 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
25690 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
256a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
256b0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
256c0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
256d0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
256e0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
256f0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
25700 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
25710 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
25720 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
25730 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
25740 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
25750 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
25760 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
25770 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
25780 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
25790 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
257a0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
257b0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
257c0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
257d0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
257e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
257f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
25800 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
25810 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
25820 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
25830 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
25840 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
25850 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
25860 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
25870 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
25880 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
25890 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
258a0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
258b0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
258c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
258d0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
258e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
258f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
25900 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
25910 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
25920 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
25930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
25940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
25950 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
25960 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
25970 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
25980 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
25990 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
259a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
259b0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
259c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
259d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
259e0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
259f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
25a00 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
25a10 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
25a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
25a30 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
25a40 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
25a50 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
25a60 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
25a70 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
25a80 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
25a90 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
25aa0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
25ab0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
25ac0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
25ad0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
25ae0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
25af0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
25b00 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
25b10 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
25b20 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
25b30 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
25b40 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
25b50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
25b60 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
25b70 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
25b80 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
25b90 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
25ba0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
25bb0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
25bc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25bd0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
25be0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
25bf0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
25c00 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
25c10 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
25c20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
25c30 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
25c40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
25c50 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
25c60 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
25c70 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
25c80 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
25c90 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
25ca0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
25cb0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
25cc0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
25cd0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
25ce0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
25cf0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
25d00 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
25d10 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
25d20 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
25d30 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
25d40 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
25d50 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
25d60 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
25d70 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
25d80 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
25d90 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
25da0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
25db0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
25dc0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
25dd0 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  k.  Invoking.** 
25de0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
25df0 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71 6c  trace()] or [sql
25e00 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
25e10 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68 65   will cancel the
25e20 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  .** profile call
25e30 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  back..*/.SQLITE_
25e40 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
25e50 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
25e60 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
25e70 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
25e80 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
25e90 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
25ea0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
25eb0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
25ec0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
25ed0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
25ee0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
25ef0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
25f00 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
25f10 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
25f20 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
25f30 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
25f40 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
25f50 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
25f60 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
25f70 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
25f80 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
25f90 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
25fa0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
25fb0 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
25fc0 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a  The M argument.*
25fd0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
25fe0 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d  ace_v2(D,M,X,P)]
25ff0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
26000 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
26010 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
26020 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
26030 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
26040 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
26050 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
26060 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
26070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
26080 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
26090 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
260a0 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
260b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
260c0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
260d0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
260e0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
260f0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
26100 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
26110 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
26120 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
26130 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
26140 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
26150 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
26160 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
26170 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
26180 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
26190 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
261a0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
261b0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
261c0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
261d0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
261e0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
261f0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
26200 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
26210 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
26220 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
26230 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
26240 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
26250 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
26260 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
26270 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
26280 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
26290 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
262a0 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
262b0 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
262c0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
262d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
262e0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
262f0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
26300 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
26310 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
26320 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
26330 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
26340 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26350 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
26360 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
26370 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
26380 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
26390 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
263a0 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
263b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
263c0 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
263d0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
263e0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
263f0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
26400 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
26410 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
26420 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
26430 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
26440 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
26450 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
26460 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
26470 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
26480 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
26490 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
264a0 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
264b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
264c0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
264d0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
264e0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
264f0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
26500 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
26510 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
26520 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
26530 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
26540 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
26550 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
26560 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
26570 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
26580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
26590 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
265a0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
265b0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
265c0 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
265d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
265e0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
265f0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
26600 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
26610 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
26620 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
26630 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
26640 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
26650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26660 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
26670 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
26680 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
26690 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
266a0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
266b0 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
266c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
266d0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
266e0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
266f0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
26700 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
26710 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
26720 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
26730 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
26740 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
26750 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
26760 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
26770 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
26780 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
26790 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
267a0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
267b0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
267c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
267d0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
267e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
267f0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
26800 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
26810 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
26820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
26830 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
26840 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
26850 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
26860 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
26870 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
26880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26890 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
268a0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
268b0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
268c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
268d0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
268e0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
268f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
26900 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
26910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
26920 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
26930 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
26940 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
26950 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
26960 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
26970 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
26980 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
26990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
269a0 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
269b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
269c0 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
269d0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
269e0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
269f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26a00 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
26a10 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
26a20 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
26a30 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
26a40 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
26a50 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
26a60 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
26a70 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
26a80 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
26a90 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
26aa0 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
26ab0 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
26ac0 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
26ad0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
26ae0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
26af0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
26b00 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
26b10 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
26b20 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
26b30 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
26b40 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
26b50 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
26b60 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
26b70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
26b80 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
26b90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
26ba0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
26bb0 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
26bc0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
26bd0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
26be0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
26bf0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
26c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
26c10 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
26c20 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
26c30 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
26c40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
26c50 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
26c60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
26c70 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
26c80 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
26c90 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
26ca0 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
26cb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
26cc0 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
26cd0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
26ce0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
26cf0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
26d00 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
26d10 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
26d20 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
26d30 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
26d40 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
26d50 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
26d60 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
26d70 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
26d80 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
26d90 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
26da0 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
26db0 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
26dc0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
26dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
26de0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
26df0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
26e00 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
26e10 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
26e20 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
26e30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26e40 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
26e50 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
26e60 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
26e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
26e80 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
26e90 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
26ea0 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
26eb0 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
26ec0 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
26ed0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
26ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26ef0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
26f00 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
26f10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
26f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26f30 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
26f40 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
26f50 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
26f60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
26f70 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
26f80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
26f90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
26fa0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
26fb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
26fc0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
26fd0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
26fe0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
26ff0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
27000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
27010 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
27020 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
27030 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
27040 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
27050 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
27060 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
27070 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
27080 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
27090 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
270a0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
270b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
270c0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
270d0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
270e0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
270f0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
27100 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
27110 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
27120 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
27130 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
27140 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
27150 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
27160 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
27170 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
27180 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
27190 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
271a0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
271b0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
271c0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
271d0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
271e0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
271f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
27200 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
27210 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
27220 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
27230 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
27240 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
27250 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
27260 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
27270 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
27280 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
27290 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
272a0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
272b0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
272c0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
272d0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
272e0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
272f0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
27300 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
27310 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
27320 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
27330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
27340 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
27350 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
27360 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
27370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
27380 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
27390 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
273a0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
273b0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
273c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
273d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
273e0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
273f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
27400 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
27410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
27420 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27430 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
27440 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
27450 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
27460 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
27470 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
27480 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
27490 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
274a0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
274b0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
274c0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
274d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
274e0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
274f0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
27500 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
27510 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
27520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
27530 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
27540 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
27550 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
27560 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
27570 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
27580 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
27590 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
275a0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
275b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
275c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
275d0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
275e0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
275f0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
27600 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
27610 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
27620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27630 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
27640 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
27650 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
27660 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
27670 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
27680 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
27690 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
276a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
276b0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
276c0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
276d0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
276e0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
276f0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
27700 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
27710 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
27720 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
27730 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
27740 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
27750 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
27760 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
27770 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
27780 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
27790 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
277a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
277b0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
277c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
277d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
277e0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
277f0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
27800 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
27810 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
27820 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
27830 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
27840 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
27850 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
27860 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
27870 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
27880 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
27890 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
278a0 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
278b0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
278c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
278d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
278e0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
278f0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
27900 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
27910 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
27920 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
27930 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
27940 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27950 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
27960 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
27970 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
27980 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
27990 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
279a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
279b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
279c0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
279d0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
279e0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
279f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
27a00 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
27a10 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
27a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27a30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
27a40 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
27a50 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
27a60 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
27a70 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
27a80 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
27a90 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
27aa0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
27ab0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
27ac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27ad0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
27ae0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
27af0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27b00 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
27b10 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
27b20 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
27b30 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
27b40 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
27b50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
27b60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
27b70 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
27b80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
27b90 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
27ba0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27bb0 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
27bc0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
27bd0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
27be0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
27bf0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
27c00 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
27c10 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
27c20 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
27c30 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
27c40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
27c50 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
27c60 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
27c70 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
27c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
27c90 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
27ca0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
27cb0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
27cc0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
27cd0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
27ce0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
27cf0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
27d00 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
27d10 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
27d20 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
27d30 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
27d40 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
27d50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
27d60 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
27d70 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
27d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
27d90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
27da0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
27db0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
27dc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
27dd0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
27de0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
27df0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
27e00 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
27e10 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
27e20 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
27e30 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
27e40 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
27e50 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
27e60 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
27e70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
27e80 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
27e90 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
27ea0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
27eb0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
27ec0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27ed0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
27ee0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
27ef0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
27f00 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
27f10 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
27f20 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
27f30 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
27f40 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
27f50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
27f60 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
27f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
27f80 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
27f90 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
27fa0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
27fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27fc0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
27fd0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
27fe0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
27ff0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
28000 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
28010 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
28020 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
28030 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
28040 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
28050 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
28060 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
28070 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
28080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28090 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
280a0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
280b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
280c0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
280d0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
280e0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
280f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
28100 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
28110 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
28120 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
28130 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
28140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28150 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
28160 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
28170 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
28180 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
28190 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
281a0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
281b0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
281c0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
281d0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
281e0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
281f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
28200 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
28210 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
28220 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
28230 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
28240 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
28250 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
28260 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
28270 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
28280 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28290 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
282a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
282b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
282c0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
282d0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
282e0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
282f0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
28300 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
28310 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
28320 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
28330 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28340 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
28350 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
28360 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
28370 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
28380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
28390 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
283a0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
283b0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
283c0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
283d0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
283e0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
283f0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
28400 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
28410 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
28420 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
28430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
28440 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
28450 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
28460 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
28470 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
28480 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
28490 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
284a0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
284b0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
284c0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
284d0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
284e0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
284f0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
28500 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
28510 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
28520 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
28530 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
28540 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
28550 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
28560 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
28570 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
28580 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
28590 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
285a0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
285b0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
285c0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
285d0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
285e0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
285f0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
28600 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
28610 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
28620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
28630 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
28640 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
28650 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
28660 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
28670 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
28680 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
28690 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
286a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
286b0 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
286c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
286d0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
286e0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
286f0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
28700 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
28710 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
28720 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
28730 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
28740 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
28750 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
28760 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67  in the third arg
28770 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
28780 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
28790 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
287a0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
287b0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
287c0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
287d0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
287e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
287f0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
28800 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
28810 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
28820 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
28830 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
28840 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
28850 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
28860 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
28870 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
28880 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
28890 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
288a0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
288b0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
288c0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
288d0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
288e0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
288f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
28900 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
28910 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
28920 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
28930 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
28940 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
28950 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
28960 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
28970 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
28980 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
28990 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
289a0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
289b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
289c0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
289d0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
289e0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
289f0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
28a00 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
28a10 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
28a20 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
28a30 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
28a40 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
28a50 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
28a60 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
28a70 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
28a80 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
28a90 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
28aa0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
28ab0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
28ac0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
28ad0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
28ae0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
28af0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
28b00 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
28b10 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
28b20 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
28b30 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
28b40 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
28b50 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
28b60 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
28b70 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
28b80 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
28b90 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
28ba0 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
28bb0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
28bc0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
28bd0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
28be0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
28bf0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
28c00 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
28c10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28c20 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
28c30 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
28c40 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
28c50 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
28c60 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
28c70 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
28c80 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
28c90 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
28ca0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
28cb0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
28cc0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
28cd0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
28ce0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
28cf0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
28d00 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
28d10 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
28d20 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
28d30 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
28d40 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
28d50 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
28d60 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
28d70 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
28d80 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
28d90 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
28da0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
28db0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
28dc0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
28dd0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
28de0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
28df0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
28e00 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
28e10 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
28e20 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
28e30 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
28e40 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
28e50 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
28e60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
28e70 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
28e80 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
28e90 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
28ea0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
28eb0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
28ec0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
28ed0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
28ee0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
28ef0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
28f00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28f10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
28f20 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
28f30 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
28f40 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
28f50 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
28f60 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
28f70 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
28f80 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
28f90 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
28fa0 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
28fb0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
28fc0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
28fd0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
28fe0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
28ff0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
29000 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
29010 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
29020 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
29030 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
29040 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
29050 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
29060 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
29070 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
29080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29090 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
290a0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
290b0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
290c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
290d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
290e0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
290f0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
29100 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
29110 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
29120 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
29130 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
29140 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
29150 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
29160 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
29170 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
29180 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
29190 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
291a0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
291b0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
291c0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
291d0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
291e0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
291f0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
29200 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
29210 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
29220 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
29230 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
29240 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
29250 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
29260 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
29270 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
29280 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
29290 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
292a0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
292b0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
292c0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
292d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
292e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
292f0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
29300 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
29310 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
29320 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
29330 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
29340 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
29350 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
29360 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
29370 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
29380 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
29390 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
293a0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
293b0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
293c0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
293d0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
293e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
293f0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
29400 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
29410 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
29420 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
29430 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
29440 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
29450 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
29460 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
29470 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
29480 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
29490 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
294a0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
294b0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
294c0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
294d0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
294e0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
294f0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
29500 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
29510 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
29520 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
29530 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
29540 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
29550 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
29560 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
29570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
29580 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
29590 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
295a0 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
295b0 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
295c0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
295d0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
295e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
295f0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
29600 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
29610 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
29620 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
29630 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
29640 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
29650 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
29660 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
29670 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
29680 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
29690 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
296a0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
296b0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
296c0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
296d0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
296e0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
296f0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
29700 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
29710 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
29720 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
29730 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
29740 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
29750 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
29760 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
29770 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
29780 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
29790 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
297a0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
297b0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
297c0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
297d0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
297e0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
297f0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
29800 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
29810 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
29820 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
29830 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
29840 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
29850 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
29860 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
29870 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
29880 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
29890 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
298a0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
298b0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
298c0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
298d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
298e0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
298f0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
29900 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
29910 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
29920 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
29930 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
29940 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
29950 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
29960 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
29970 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
29980 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
29990 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
299a0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
299b0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
299c0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
299d0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
299e0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
299f0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
29a00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
29a10 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
29a20 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
29a30 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
29a40 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
29a50 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
29a60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
29a70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
29a80 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
29a90 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
29aa0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
29ab0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
29ac0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
29ad0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
29ae0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
29af0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29b00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
29b10 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
29b20 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
29b30 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
29b40 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
29b50 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
29b60 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
29b70 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
29b80 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
29b90 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
29ba0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
29bb0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
29bc0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
29bd0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
29be0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
29bf0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
29c00 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
29c10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29c20 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
29c30 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
29c40 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
29c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
29c60 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
29c70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
29c80 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
29c90 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
29ca0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
29cb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29cc0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
29cd0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
29ce0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29cf0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
29d00 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
29d10 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
29d20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
29d30 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
29d40 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
29d50 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
29d60 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
29d70 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
29d80 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
29d90 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
29da0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
29db0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
29dc0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
29dd0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
29de0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
29df0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
29e00 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
29e10 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
29e20 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
29e30 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
29e40 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
29e50 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
29e60 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
29e70 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
29e80 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
29e90 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
29ea0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
29eb0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
29ec0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
29ed0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
29ee0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
29ef0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
29f00 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
29f10 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
29f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
29f30 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
29f40 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
29f50 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
29f60 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
29f70 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
29f80 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
29f90 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
29fa0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
29fb0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
29fc0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
29fd0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
29fe0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
29ff0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
2a000 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
2a010 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
2a020 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
2a030 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
2a040 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
2a050 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
2a060 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
2a070 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
2a080 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
2a090 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
2a0a0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
2a0b0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
2a0c0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
2a0d0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
2a0e0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
2a0f0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
2a100 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
2a110 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
2a120 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
2a130 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
2a140 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
2a150 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
2a160 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
2a170 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
2a180 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
2a190 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
2a1a0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
2a1b0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
2a1c0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
2a1d0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
2a1e0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
2a1f0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
2a200 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
2a210 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
2a220 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2a230 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
2a240 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
2a250 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
2a260 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
2a270 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
2a280 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
2a290 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2a2a0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
2a2b0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
2a2c0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
2a2d0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
2a2e0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
2a2f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2a300 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2a310 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
2a320 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
2a330 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
2a340 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
2a350 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
2a360 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
2a370 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
2a380 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
2a390 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
2a3a0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
2a3b0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
2a3c0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
2a3d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
2a3e0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
2a3f0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
2a400 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
2a410 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
2a420 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
2a430 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
2a440 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
2a450 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
2a460 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
2a470 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
2a480 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
2a490 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
2a4a0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
2a4b0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
2a4c0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
2a4d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
2a4e0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
2a4f0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
2a500 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
2a510 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
2a520 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
2a530 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a540 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
2a550 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
2a560 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
2a570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
2a580 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
2a590 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
2a5a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
2a5b0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
2a5c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
2a5d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
2a5e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
2a5f0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
2a600 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
2a610 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
2a620 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
2a630 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
2a640 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
2a650 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
2a660 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
2a670 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
2a680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
2a690 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
2a6a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
2a6b0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
2a6c0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
2a6d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
2a6e0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
2a6f0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
2a700 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
2a710 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
2a720 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
2a730 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
2a740 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
2a750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a760 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
2a770 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
2a780 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
2a790 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
2a7a0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
2a7b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
2a7c0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
2a7d0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
2a7e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
2a7f0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
2a800 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
2a810 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
2a820 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
2a830 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
2a840 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
2a850 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2a860 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
2a870 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
2a880 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
2a890 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
2a8a0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
2a8b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
2a8c0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
2a8d0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
2a8e0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
2a8f0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
2a900 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
2a910 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
2a920 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
2a930 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
2a940 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2a950 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
2a960 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
2a970 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
2a980 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
2a990 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
2a9a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
2a9b0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
2a9c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
2a9d0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
2a9e0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
2a9f0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
2aa00 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
2aa10 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
2aa20 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
2aa30 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
2aa40 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
2aa50 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
2aa60 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
2aa70 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
2aa80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
2aa90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
2aaa0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
2aab0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
2aac0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
2aad0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
2aae0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
2aaf0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
2ab00 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
2ab10 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
2ab20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
2ab30 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
2ab40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
2ab50 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
2ab60 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
2ab70 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
2ab80 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
2ab90 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
2aba0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
2abb0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
2abc0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
2abd0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
2abe0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
2abf0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
2ac00 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
2ac10 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
2ac20 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
2ac30 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
2ac40 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
2ac50 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
2ac60 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
2ac70 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
2ac80 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
2ac90 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
2aca0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
2acb0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
2acc0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
2acd0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
2ace0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
2acf0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
2ad00 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
2ad10 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
2ad20 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
2ad30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
2ad40 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
2ad50 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
2ad60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
2ad70 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
2ad80 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2ad90 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
2ada0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
2adb0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
2adc0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
2add0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
2ade0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2adf0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
2ae00 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
2ae10 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
2ae20 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
2ae30 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
2ae40 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
2ae50 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
2ae60 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
2ae70 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
2ae80 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
2ae90 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
2aea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2aeb0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
2aec0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
2aed0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
2aee0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
2aef0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
2af00 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
2af10 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
2af20 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
2af30 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2af40 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
2af50 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 53  sirable..**.** S
2af60 65 65 20 74 68 65 20 5b 55 52 49 20 66 69 6c 65  ee the [URI file
2af70 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  name] documentat
2af80 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
2af90 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2afa0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2afb0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
2afc0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
2afd0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
2afe0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
2aff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
2b000 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
2b010 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
2b020 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
2b030 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
2b040 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2b050 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
2b060 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
2b070 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2b080 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
2b090 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
2b0a0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
2b0b0 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
2b0c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
2b0d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b0e0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
2b0f0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
2b100 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
2b110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
2b120 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
2b130 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
2b140 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
2b150 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2b160 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
2b170 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2b180 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
2b190 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
2b1a0 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  l..** ^The sqlit
2b1b0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
2b1c0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
2b1d0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
2b1e0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
2b1f0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
2b200 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
2b210 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
2b220 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
2b230 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
2b240 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
2b250 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72 65  ** The values re
2b260 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b270 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64 2f  3_errcode() and/
2b280 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  or.** sqlite3_ex
2b290 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
2b2a0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77 69   might change wi
2b2b0 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c 6c  th each API call
2b2c0 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 65  ..** Except, the
2b2d0 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 65  re are some inte
2b2e0 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20  rfaces that are 
2b2f0 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65  guaranteed to ne
2b300 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  ver.** change th
2b310 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 65  e value of the e
2b320 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20  rror code.  The 
2b330 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 65  error-code prese
2b340 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 61  rving.** interfa
2b350 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  ces are:.**.** <
2b360 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  ul>.** <li> sqli
2b370 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  te3_errcode().**
2b380 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 78   <li> sqlite3_ex
2b390 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
2b3a0 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  .** <li> sqlite3
2b3b0 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69  _errmsg().** <li
2b3c0 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  > sqlite3_errmsg
2b3d0 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  16().** </ul>.**
2b3e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b3f0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
2b400 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
2b410 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
2b420 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
2b430 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
2b440 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
2b450 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2b460 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
2b470 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
2b480 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
2b490 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2b4a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
2b4b0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
2b4c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
2b4d0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
2b4e0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
2b4f0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
2b500 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
2b510 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
2b520 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
2b530 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
2b540 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
2b550 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
2b560 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
2b570 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
2b580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
2b590 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
2b5a0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
2b5b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
2b5c0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
2b5d0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
2b5e0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
2b5f0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
2b600 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
2b610 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
2b620 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
2b630 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
2b640 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
2b650 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
2b660 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
2b670 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
2b680 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
2b690 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
2b6a0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
2b6b0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
2b6c0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
2b6d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
2b6e0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
2b6f0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
2b700 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
2b710 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
2b720 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2b730 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
2b740 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
2b750 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
2b760 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
2b770 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
2b780 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
2b790 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
2b7a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
2b7b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
2b7c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
2b7d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
2b7e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b7f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
2b800 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
2b810 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
2b820 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
2b830 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
2b840 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
2b850 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
2b860 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
2b870 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
2b880 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
2b890 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
2b8a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
2b8b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
2b8c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
2b8d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
2b8e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
2b8f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
2b900 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
2b910 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
2b920 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
2b930 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
2b940 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
2b950 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
2b960 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
2b970 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
2b980 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
2b990 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
2b9a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
2b9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
2b9c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
2b9d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
2b9e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2b9f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
2ba00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ba10 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
2ba20 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
2ba30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
2ba40 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
2ba50 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
2ba60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2ba70 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2ba80 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
2ba90 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
2baa0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
2bab0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
2bac0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
2bad0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
2bae0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2baf0 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
2bb00 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
2bb10 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
2bb20 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
2bb30 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
2bb40 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
2bb50 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
2bb60 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
2bb70 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
2bb80 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
2bb90 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
2bba0 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
2bbb0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
2bbc0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
2bbd0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
2bbe0 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
2bbf0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
2bc00 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
2bc10 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
2bc20 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
2bc30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
2bc40 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
2bc50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
2bc60 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
2bc70 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
2bc80 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
2bc90 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
2bca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
2bcb0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
2bcc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2bcd0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
2bce0 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
2bcf0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
2bd00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2bd10 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
2bd20 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
2bd30 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
2bd40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
2bd50 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
2bd60 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
2bd70 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
2bd80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2bd90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2bda0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
2bdb0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
2bdc0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
2bdd0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
2bde0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
2bdf0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
2be00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2be10 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
2be20 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
2be30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
2be40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
2be50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2be60 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
2be70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2be80 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
2be90 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
2bea0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
2beb0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
2bec0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
2bed0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
2bee0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
2bef0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
2bf00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2bf10 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2bf20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
2bf30 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
2bf40 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
2bf50 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
2bf60 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
2bf70 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
2bf80 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
2bf90 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
2bfa0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
2bfb0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
2bfc0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
2bfd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2bfe0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
2bff0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
2c000 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
2c010 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
2c020 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
2c030 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
2c040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
2c050 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
2c060 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
2c070 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
2c080 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
2c090 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
2c0a0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
2c0b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
2c0c0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
2c0d0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
2c0e0 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
2c0f0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
2c100 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
2c110 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
2c120 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
2c130 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
2c140 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
2c150 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
2c160 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
2c170 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
2c180 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
2c190 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
2c1a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
2c1b0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
2c1c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2c1d0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
2c1e0 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
2c1f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
2c200 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
2c210 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
2c220 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
2c230 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
2c240 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
2c250 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
2c260 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
2c270 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
2c280 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
2c290 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
2c2a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c2b0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
2c2c0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
2c2d0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
2c2e0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
2c2f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
2c300 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
2c310 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
2c320 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
2c330 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
2c340 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
2c350 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
2c360 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
2c370 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
2c380 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
2c390 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
2c3a0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
2c3b0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
2c3c0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
2c3d0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
2c3e0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
2c3f0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
2c400 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
2c410 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
2c420 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
2c430 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
2c440 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
2c450 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
2c460 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
2c470 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
2c480 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
2c490 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
2c4a0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
2c4b0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
2c4c0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
2c4d0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
2c4e0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
2c4f0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
2c500 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
2c510 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
2c520 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
2c530 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
2c540 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
2c550 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
2c560 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
2c570 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2c580 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
2c590 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
2c5a0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
2c5b0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
2c5c0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
2c5d0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
2c5e0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
2c5f0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
2c600 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2c610 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
2c620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
2c630 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
2c640 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
2c650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c660 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
2c670 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
2c680 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
2c690 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
2c6a0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
2c6b0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2c6c0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2c6d0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
2c6e0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
2c6f0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
2c700 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
2c710 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2c720 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
2c730 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
2c740 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
2c750 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
2c760 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
2c770 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2c780 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
2c790 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
2c7a0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
2c7b0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2c7c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2c7d0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2c7e0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
2c7f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c800 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
2c810 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
2c820 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
2c830 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
2c840 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2c850 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2c860 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c870 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2c880 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c890 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2c8a0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
2c8b0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
2c8c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2c8d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2c8e0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
2c8f0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
2c900 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2c910 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2c920 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
2c930 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
2c940 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
2c950 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2c960 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
2c970 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
2c980 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
2c990 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
2c9a0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
2c9b0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
2c9c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2c9d0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2c9e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c9f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2ca00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ca10 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
2ca20 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
2ca30 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
2ca40 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2ca50 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ca60 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
2ca70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2ca80 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2ca90 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
2caa0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2cab0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
2cac0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
2cad0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
2cae0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2caf0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2cb00 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2cb10 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
2cb20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2cb30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2cb40 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
2cb50 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
2cb60 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
2cb70 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
2cb80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2cb90 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72    If [sqlite3_pr
2cba0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
2cbb0 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  * the equivalent
2cbc0 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61   tries to alloca
2cbd0 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72  te space for mor
2cbe0 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79  e than this many
2cbf0 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61   opcodes.** in a
2cc00 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64   single prepared
2cc10 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53   statement, an S
2cc20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f  QLITE_NOMEM erro
2cc30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
2cc40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2cc50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2cc60 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
2cc70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2cc80 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
2cc90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2cca0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
2ccb0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
2ccc0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2ccd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cce0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
2ccf0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
2cd00 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
2cd10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2cd20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
2cd30 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
2cd40 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
2cd50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2cd60 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2cd70 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
2cd80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2cd90 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2cda0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2cdb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2cdc0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
2cdd0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
2cde0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
2cdf0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
2ce00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2ce10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2ce20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
2ce30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2ce40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2ce50 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
2ce60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
2ce70 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
2ce80 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
2ce90 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2cea0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
2ceb0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2cec0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2ced0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2cee0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
2cef0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2cf00 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
2cf10 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
2cf20 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2cf30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2cf40 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
2cf50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2cf60 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2cf70 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
2cf80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2cf90 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
2cfa0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
2cfb0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
2cfc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cfd0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
2cfe0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
2cff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d000 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
2d010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d020 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
2d030 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2d040 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2d050 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2d060 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
2d070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d080 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2d090 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2d0a0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
2d0b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2d0c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2d0d0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
2d0e0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2d0f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2d100 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
2d110 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
2d120 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2d130 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
2d140 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
2d150 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
2d160 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
2d170 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
2d180 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2d190 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2d1a0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
2d1b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2d1c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
2d1d0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
2d1e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2d1f0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
2d200 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
2d210 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2d220 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2d230 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
2d240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
2d250 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a  repare Flags.**.
2d260 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2d270 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2d280 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e  s flags that can
2d290 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a   be passed into.
2d2a0 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70  ** "prepFlags" p
2d2b0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2d2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d2d0 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  _v3()] and.** [s
2d2e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d2f0 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v3()] interface
2d300 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61  s..**.** New fla
2d310 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  gs may be added 
2d320 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2d330 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
2d340 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2d350 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2d360 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e  SISTENT]] ^(<dt>
2d370 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2d380 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a  ERSISTENT</dt>.*
2d390 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2d3a0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2d3b0 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69  ENT flag is a hi
2d3c0 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20  nt to the query 
2d3d0 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20  planner.** that 
2d3e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2d3f0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72  tement will be r
2d400 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f  etained for a lo
2d410 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70  ng time and.** p
2d420 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d  robably reused m
2d430 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69  any times.)^ ^Wi
2d440 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c  thout this flag,
2d450 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d460 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  e_v3()].** and [
2d470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d480 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74  6_v3()] assume t
2d490 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2d4a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2d4b0 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74  .** be used just
2d4c0 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74   once or at most
2d4d0 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64   a few times and
2d4e0 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20   then destroyed 
2d4f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2d500 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65  3_finalize()] re
2d510 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54  latively soon. T
2d520 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
2d530 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a  mentation acts.*
2d540 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62  * on this hint b
2d550 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75  y avoiding the u
2d560 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65  se of [lookaside
2d570 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e   memory] so as n
2d580 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65  ot to.** deplete
2d590 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f   the limited sto
2d5a0 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  re of lookaside 
2d5b0 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76  memory. Future v
2d5c0 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51  ersions of.** SQ
2d5d0 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20  Lite may act on 
2d5e0 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72  this hint differ
2d5f0 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ently..**.** [[S
2d600 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d610 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53 51  RMALIZE]] <dt>SQ
2d620 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52  LITE_PREPARE_NOR
2d630 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALIZE</dt>.** <
2d640 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52  dd>The SQLITE_PR
2d650 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20  EPARE_NORMALIZE 
2d660 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70 2e  flag is a no-op.
2d670 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64 0a   This flag used.
2d680 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72 65  ** to be require
2d690 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61 72  d for any prepar
2d6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ed statement tha
2d6b0 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65 20  t wanted to use 
2d6c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2d6d0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29  normalized_sql()
2d6e0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48 6f  ] interface.  Ho
2d6f0 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b 73  wever, the.** [s
2d700 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2d710 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61  d_sql()] interfa
2d720 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c 61  ce is now availa
2d730 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70 72  ble to all.** pr
2d740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d750 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  s, regardless of
2d760 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2d770 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a 2a  they use this.**
2d780 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   flag..**.** [[S
2d790 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d7a0 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c 49  _VTAB]] <dt>SQLI
2d7b0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54  TE_PREPARE_NO_VT
2d7c0 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AB</dt>.** <dd>T
2d7d0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2d7e0 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20 63  E_NO_VTAB flag c
2d7f0 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63 6f  auses the SQL co
2d800 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65 74  mpiler.** to ret
2d810 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65 72  urn an error (er
2d820 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45 5f  ror code SQLITE_
2d830 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73 74  ERROR) if the st
2d840 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a 20  atement uses.** 
2d850 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  any virtual tabl
2d860 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  es..** </dl>.*/.
2d870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2d880 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2d890 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  T              0
2d8a0 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
2d8b0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41  TE_PREPARE_NORMA
2d8c0 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LIZE            
2d8d0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
2d8e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d8f0 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  O_VTAB          
2d900 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a 0a         0x04../*.
2d910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2d920 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
2d930 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
2d940 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
2d950 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2d960 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d970 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2d980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2d990 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2d9a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2d9b0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2d9c0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2d9d0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2d9e0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2d9f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2da00 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65  es.  Or, in othe
2da10 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72  r words, these r
2da20 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63  outines.** are c
2da30 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  onstructors for 
2da40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2da50 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
2da60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65  .**.** The prefe
2da70 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20  rred routine to 
2da80 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f  use is [sqlite3_
2da90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20  prepare_v2()].  
2daa0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2dab0 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72  prepare()] inter
2dac0 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61  face is legacy a
2dad0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  nd should be avo
2dae0 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  ided..** [sqlite
2daf0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2db00 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72  has an extra "pr
2db10 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20  epFlags" option 
2db20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20  that is used.** 
2db30 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70  for special purp
2db40 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  oses..**.** The 
2db50 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38  use of the UTF-8
2db60 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70   interfaces is p
2db70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c  referred, as SQL
2db80 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  ite currently.**
2db90 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e   does all parsin
2dba0 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20  g using UTF-8.  
2dbb0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2dbc0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
2dbd0 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65  ed.** as a conve
2dbe0 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46  nience.  The UTF
2dbf0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77  -16 interfaces w
2dc00 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e  ork by convertin
2dc10 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74  g the.** input t
2dc20 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20  ext into UTF-8, 
2dc30 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68  then invoking th
2dc40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2dc50 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e  UTF-8 interface.
2dc60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2dc70 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2dc80 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2dc90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2dca0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2dcb0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2dcc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2dcd0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2dce0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2dcf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2dd00 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2dd10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dd20 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2dd30 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2dd40 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2dd50 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2dd60 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2dd70 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2dd80 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2dd90 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2dda0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2ddb0 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71  e3_prepare(), sq
2ddc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ddd0 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2dde0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a  e3_prepare_v3().
2ddf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
2de00 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
2de10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2de20 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2de30 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2de40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2de50 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d  16_v3() use UTF-
2de60 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2de70 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2de80 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2de90 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2dea0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2deb0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2dec0 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2ded0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2dee0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2def0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2df00 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2df10 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2df20 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2df30 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2df40 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2df50 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2df60 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2df70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2df80 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2df90 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2dfa0 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2dfb0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2dfc0 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2dfd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2dfe0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2dff0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2e000 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2e010 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2e020 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2e030 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2e040 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2e050 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2e060 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2e070 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2e080 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2e090 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2e0a0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2e0b0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2e0c0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2e0d0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2e0e0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2e0f0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2e100 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2e110 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2e120 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2e130 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2e140 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2e150 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2e160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e170 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2e180 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2e190 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2e1a0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2e1b0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2e1c0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2e1d0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2e1e0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2e1f0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2e200 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2e210 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2e220 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2e230 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2e240 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2e250 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2e260 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2e270 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2e280 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2e290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2e2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2e2b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2e2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2e2d0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2e2e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2e2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2e300 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2e310 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2e320 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2e330 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e340 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2e350 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2e360 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2e370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2e380 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69  epare_v2(), sqli
2e390 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2e3a0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2e3b0 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2e3c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e3d0 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63  16_v3() interfac
2e3e0 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64  es are recommend
2e3f0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
2e400 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20  rograms..** The 
2e410 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2e420 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   (sqlite3_prepar
2e430 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2e440 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20  prepare16()).** 
2e450 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
2e460 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2e470 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
2e480 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
2e490 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
2e4a0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
2e4b0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
2e4c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
2e4d0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
2e4e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2e4f0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
2e500 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
2e510 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2e520 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
2e530 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
2e540 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
2e550 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
2e560 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
2e570 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
2e580 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
2e590 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2e5a0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
2e5b0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
2e5c0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
2e5d0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
2e5e0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
2e5f0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
2e600 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
2e610 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2e620 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
2e630 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
2e640 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
2e650 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
2e660 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
2e670 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
2e680 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
2e690 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e6a0 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
2e6b0 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
2e6c0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2e6d0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
2e6e0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
2e6f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2e700 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
2e710 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
2e720 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
2e730 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2e740 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
2e750 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
2e760 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
2e770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
2e780 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
2e790 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
2e7a0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
2e7b0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
2e7c0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
2e7d0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
2e7e0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
2e7f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e800 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
2e810 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
2e820 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
2e830 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
2e840 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
2e850 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
2e860 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
2e870 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
2e880 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
2e890 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
2e8a0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2e8b0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2e8c0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
2e8d0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
2e8e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
2e8f0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
2e900 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
2e910 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
2e920 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2e930 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
2e940 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
2e950 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2e960 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2e970 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
2e980 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
2e990 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
2e9a0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
2e9b0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
2e9c0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
2e9d0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
2e9e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2e9f0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
2ea00 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
2ea10 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
2ea20 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
2ea30 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
2ea40 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
2ea50 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2ea60 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
2ea70 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
2ea80 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2ea90 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
2eaa0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
2eab0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
2eac0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
2ead0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
2eae0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
2eaf0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
2eb00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
2eb10 42 4c 45 5f 53 54 41 54 34 5d 20 63 6f 6d 70 69  BLE_STAT4] compi
2eb20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
2eb30 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
2eb40 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
2eb50 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70  ** <p>^sqlite3_p
2eb60 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66  repare_v3() diff
2eb70 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ers from sqlite3
2eb80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e  _prepare_v2() on
2eb90 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20  ly in having.** 
2eba0 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c  the extra prepFl
2ebb0 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77  ags parameter, w
2ebc0 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72  hich is a bit ar
2ebd0 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  ray consisting o
2ebe0 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  f zero or.** mor
2ebf0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
2ec00 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2ec10 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41  ENT|SQLITE_PREPA
2ec20 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54  RE_*] flags.  ^T
2ec30 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
2ec40 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72  epare_v2() inter
2ec50 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74  face works exact
2ec60 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ly the same as.*
2ec70 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2ec80 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65  e_v3() with a ze
2ec90 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ro prepFlags par
2eca0 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ameter..*/.int s
2ecb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2ecc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2ecd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2ece0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2ecf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2ed00 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2ed10 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2ed20 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2ed30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ed40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ed50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ed60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ed70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2ed80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ed90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2eda0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2edb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2edc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2edd0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ede0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2edf0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2ee00 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2ee10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ee20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2ee30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2ee40 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2ee50 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2ee60 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2ee70 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ee80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ee90 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2eea0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2eeb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2eec0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2eed0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2eee0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2eef0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2ef00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2ef10 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2ef20 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2ef30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2ef40 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71  prepare_v3(.  sq
2ef50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ef60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ef70 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ef80 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ef90 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2efa0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2efb0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2efc0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2efd0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2efe0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2eff0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2f000 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2f010 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2f020 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2f030 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2f040 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2f050 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2f060 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2f070 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2f080 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2f090 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2f0a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2f0b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2f0c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2f0d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2f0e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2f0f0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2f100 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2f110 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2f120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2f130 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2f140 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2f150 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2f160 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2f170 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2f180 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2f190 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2f1a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2f1b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2f1c0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2f1d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2f1e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2f1f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2f200 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2f210 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2f220 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2f230 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2f240 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2f250 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2f260 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2f270 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2f280 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2f290 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2f2a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2f2b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2f2c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2f2d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2f2e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2f2f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2f300 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2f310 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2f320 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2f330 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2f340 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2f350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f360 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v3(.  sqlite3 
2f370 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2f380 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2f390 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2f3a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2f3b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2f3c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2f3d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2f3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f3f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2f400 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2f410 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20  . */.  unsigned 
2f420 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f  int prepFlags, /
2f430 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53  * Zero or more S
2f440 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66  QLITE_PREPARE_ f
2f450 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65  lags */.  sqlite
2f460 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2f470 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2f480 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2f490 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2f4a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2f4b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2f4c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2f4d0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2f4e0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2f4f0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2f500 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2f510 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2f520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c  ^The sqlite3_sql
2f530 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2f540 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f550 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  to a copy of the
2f560 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65   UTF-8.** SQL te
2f570 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2f580 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f590 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61  ement] P if P wa
2f5a0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2f5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f5c0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2f5d0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a  _prepare_v3()],.
2f5e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2f5f0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
2f600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f610 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v3()]..** ^Th
2f620 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2f630 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2f640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2f650 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2f660 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2f670 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2f680 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2f690 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2f6a0 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2f6b0 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2f6c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f6d0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50  normalized_sql(P
2f6e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f6f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f700 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2f710 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2f720 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51 4c  e normalized SQL
2f730 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2f740 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20 20  d statement P.  
2f750 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63 73  The.** semantics
2f760 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c 69   used to normali
2f770 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  ze a SQL stateme
2f780 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66 69  nt are unspecifi
2f790 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a 2a  ed and subject.*
2f7a0 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41 74  * to change.  At
2f7b0 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74 65   a minimum, lite
2f7c0 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c 20  ral values will 
2f7d0 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74 68  be replaced with
2f7e0 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c 61   suitable.** pla
2f7f0 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a 2a  ceholders..**.**
2f800 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2f810 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  if a prepared st
2f820 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74  atement is creat
2f830 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
2f840 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54  .** text "SELECT
2f850 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20   $abc,:xyz" and 
2f860 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62  if parameter $ab
2f870 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e  c is bound to in
2f880 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e  teger 2345.** an
2f890 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a  d parameter :xyz
2f8a0 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65   is unbound, the
2f8b0 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20  n sqlite3_sql() 
2f8c0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74  will return.** t
2f8d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69  he original stri
2f8e0 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63  ng, "SELECT $abc
2f8f0 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74  ,:xyz" but sqlit
2f900 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2f910 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2f920 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55   "SELECT 2345,NU
2f930 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  LL".)^.**.** ^Th
2f940 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2f950 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61  ed_sql() interfa
2f960 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  ce returns NULL 
2f970 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
2f980 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61  memory.** is ava
2f990 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74  ilable to hold t
2f9a0 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66  he result, or if
2f9b0 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c   the result woul
2f9c0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2f9d0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69  the maximum stri
2f9e0 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d  ng length determ
2f9f0 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c  ined by the [SQL
2fa00 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2fa10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  ]..**.** ^The [S
2fa20 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
2fa30 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
2fa40 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69  time option limi
2fa50 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ts the size of.*
2fa60 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  * bound paramete
2fa70 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e  r expansions.  ^
2fa80 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2fa90 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
2faa0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63  time.** option c
2fab0 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78  auses sqlite3_ex
2fac0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20  panded_sql() to 
2fad0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55  always return NU
2fae0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2faf0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2fb00 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  by sqlite3_sql(P
2fb10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e 6f  ) and sqlite3_no
2fb20 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 0a  rmalized_sql(P).
2fb30 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20 62  ** are managed b
2fb40 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72 65  y SQLite and are
2fb50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2fb60 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72  reed when the pr
2fb70 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2fb80 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2fb90 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2fba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2fbb0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2fbc0 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2fbd0 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2fbe0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2fbf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2fc00 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2fc10 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2fc20 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2fc30 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2fc40 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2fc50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2fc60 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2fc70 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2fc80 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2fc90 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2fca0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e 73  mt *pStmt);.cons
2fcb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2fcc0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 73  normalized_sql(s
2fcd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fce0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2fcf0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2fd00 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2fd10 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2fd20 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2fd30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2fd40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fd50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2fd60 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2fd70 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2fd80 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2fd90 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2fda0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fdb0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2fdc0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2fdd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2fde0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2fdf0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2fe00 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2fe10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2fe20 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2fe30 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2fe40 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2fe50 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2fe60 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2fe70 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2fe80 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2fe90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2fea0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2feb0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2fec0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2fed0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2fee0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2fef0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2ff00 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2ff10 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2ff20 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2ff30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2ff40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2ff50 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2ff60 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2ff70 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2ff80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2ff90 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2ffa0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2ffb0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2ffc0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2ffd0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2ffe0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2fff0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
30000 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
30010 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
30020 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
30030 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
30040 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
30050 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
30060 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
30070 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
30080 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
30090 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
300a0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
300b0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
300c0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
300d0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
300e0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
300f0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
30100 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
30110 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
30120 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
30130 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
30140 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
30150 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
30160 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
30170 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
30180 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
30190 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
301a0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
301b0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
301c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
301d0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
301e0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
301f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
30200 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
30210 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
30220 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
30230 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
30240 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54  s on disk..** ^T
30250 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
30260 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72  readonly() inter
30270 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
30280 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69  e for [BEGIN] si
30290 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d  nce.** [BEGIN] m
302a0 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72  erely sets inter
302b0 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74  nal flags, but t
302c0 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  he [BEGIN|BEGIN 
302d0 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a  IMMEDIATE] and.*
302e0 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45  * [BEGIN|BEGIN E
302f0 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e  XCLUSIVE] comman
30300 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20  ds do touch the 
30310 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a  database and so.
30320 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
30330 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72  readonly() retur
30340 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f  ns false for tho
30350 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a  se commands..*/.
30360 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
30370 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
30380 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
303a0 20 51 75 65 72 79 20 54 68 65 20 45 58 50 4c 41   Query The EXPLA
303b0 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20 41  IN Setting For A
303c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
303d0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
303e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
303f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
30400 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53 29  tmt_isexplain(S)
30410 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30420 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20 70  ns 1 if the.** p
30430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30440 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49  t S is an EXPLAI
30450 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 20  N statement, or 
30460 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61 74  2 if the.** stat
30470 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45 58  ement S is an EX
30480 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e  PLAIN QUERY PLAN
30490 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
304a0 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e  3_stmt_isexplain
304b0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
304c0 74 75 72 6e 73 20 30 20 69 66 20 53 20 69 73 0a  turns 0 if S is.
304d0 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 73  ** an ordinary s
304e0 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e 55  tatement or a NU
304f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
30500 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
30510 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69 74 65  isexplain(sqlite
30520 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30540 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
30550 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30560 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
30570 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30580 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
305a0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
305b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
305c0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
305d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
305e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
305f0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
30600 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
30610 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
30620 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
30630 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
30640 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
30650 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
30660 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
30670 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
30680 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
30690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
306a0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
306b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
306c0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
306d0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
306e0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
306f0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
30700 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
30710 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
30720 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
30730 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
30740 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
30750 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
30760 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
30770 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
30780 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
30790 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
307a0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
307b0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
307c0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
307d0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
307e0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
307f0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
30800 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
30810 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
30820 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
30830 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
30840 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
30850 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
30860 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
30870 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
30880 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
30890 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
308a0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
308b0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
308c0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
308d0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
308e0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
308f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30900 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
30910 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
30920 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
30930 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
30940 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
30950 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30960 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
30970 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
30980 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
30990 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
309a0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
309b0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
309c0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
309d0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
309e0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
309f0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
30a00 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
30a10 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
30a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30a30 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
30a40 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
30a50 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
30a60 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
30a70 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
30a80 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
30a90 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
30aa0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
30ab0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
30ac0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
30ad0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
30ae0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
30af0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
30b00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
30b10 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
30b20 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
30b30 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
30b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
30b50 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
30b60 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
30b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
30b80 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
30b90 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
30ba0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
30bb0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
30bc0 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
30bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30be0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
30bf0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
30c00 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
30c10 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
30c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
30c30 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
30c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
30c50 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
30c60 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
30c70 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
30c80 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
30c90 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
30ca0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
30cb0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
30cc0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
30cd0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
30ce0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
30cf0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
30d00 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
30d10 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
30d20 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
30d30 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
30d40 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
30d50 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
30d60 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
30d70 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
30d80 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
30d90 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
30da0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
30db0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
30dc0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
30dd0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
30de0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
30df0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
30e00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
30e10 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
30e20 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
30e30 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
30e40 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
30e50 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
30e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30e70 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
30e80 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
30e90 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
30ea0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
30eb0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
30ec0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
30ed0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
30ee0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
30ef0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
30f00 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
30f10 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
30f20 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
30f30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30f40 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
30f50 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
30f60 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
30f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30f80 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
30f90 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
30fa0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
30fb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30fc0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
30fd0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30fe0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
30ff0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
31000 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
31010 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
31020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31030 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
31040 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
31050 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31060 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
31070 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
31080 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  as arguments.** 
31090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
310a0 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71  lt_value()], [sq
310b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
310c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
310d0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
310e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
310f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
31100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
31110 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
31120 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
31130 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
31140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
31150 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
31160 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
31170 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76  _value sqlite3_v
31180 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
31190 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
311a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
311b0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
311c0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
311d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
311e0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
311f0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
31200 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
31210 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
31220 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
31230 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
31240 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
31250 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
31260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
31280 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
31290 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
312a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
312b0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
312c0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
312d0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
312e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
312f0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
31300 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
31310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
31320 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
31330 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
31340 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
31350 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
31360 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
31370 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
31380 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
31390 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
313a0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
313b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
313c0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
313d0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
313e0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
313f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
31400 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
31410 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
31420 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
31430 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
31440 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
31450 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
31460 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
31470 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
31480 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
31490 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
314a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
314b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
314c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
314d0 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
314e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
314f0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
31500 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
31510 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
31520 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
31530 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
31540 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
31550 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
31560 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
31570 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
31580 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
31590 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
315a0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
315b0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
315c0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
315d0 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
315e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
315f0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
31600 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
31610 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
31620 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
31630 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
31640 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
31650 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
31660 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
31670 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
31680 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
31690 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
316a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
316b0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
316c0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
316d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
316e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
316f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
31700 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
31710 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31720 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
31730 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
31740 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
31750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
31760 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
31770 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31780 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
31790 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
317a0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
317b0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
317c0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
317d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
317e0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
317f0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
31800 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
31810 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
31820 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
31830 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
31840 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
31850 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
31860 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
31870 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
31880 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
31890 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
318a0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
318b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
318c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
318d0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
318e0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
318f0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
31900 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
31910 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
31920 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
31930 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
31940 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
31950 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
31960 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
31970 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
31980 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
31990 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
319a0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
319b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
319c0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
319d0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
319e0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
319f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31a00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
31a10 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
31a20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
31a30 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31a40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
31a50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
31a60 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
31a70 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
31a80 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
31a90 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
31aa0 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
31ab0 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
31ac0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
31ad0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
31ae0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
31af0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
31b00 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
31b10 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
31b20 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
31b30 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
31b40 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
31b50 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
31b60 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
31b70 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
31b80 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
31b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
31ba0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31bb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31bc0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
31bd0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
31be0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
31bf0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
31c00 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
31c10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31c20 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
31c30 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
31c40 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
31c50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
31c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
31c70 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
31c80 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
31c90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
31ca0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
31cb0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
31cc0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
31cd0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
31ce0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
31cf0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
31d00 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
31d10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31d20 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
31d30 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
31d40 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
31d50 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
31d60 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
31d70 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
31d80 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
31d90 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
31da0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
31db0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
31dc0 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
31dd0 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
31de0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
31df0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
31e00 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
31e10 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
31e20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
31e30 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
31e40 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
31e50 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
31e60 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
31e70 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
31e80 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
31e90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
31ea0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
31eb0 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
31ec0 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
31ed0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
31ee0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
31ef0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
31f00 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
31f10 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
31f20 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
31f30 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
31f40 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
31f50 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
31f60 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
31f70 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
31f80 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 20  the call to the 
31f90 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2c 0a  bind API fails,.
31fa0 2a 2a 20 65 78 63 65 70 74 20 74 68 65 20 64 65  ** except the de
31fb0 73 74 72 75 63 74 6f 72 20 69 73 20 6e 6f 74 20  structor is not 
31fc0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 74 68  called if the th
31fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
31fe0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
31ff0 65 72 20 6f 72 20 74 68 65 20 66 6f 75 72 74 68  er or the fourth
32000 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
32010 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49 66 20 74  gative..** ^If t
32020 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
32030 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
32040 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
32050 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
32060 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
32070 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
32080 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
32090 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
320a0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
320b0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
320c0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
320d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
320e0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
320f0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
32100 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
32110 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
32120 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
32130 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
32140 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
32150 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
32160 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
32170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
32180 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
32190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
321a0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
321b0 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
321c0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
321d0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
321e0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
321f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
32200 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
32210 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
32220 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
32230 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
32240 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
32250 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
32260 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
32270 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
32280 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
32290 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
322a0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
322b0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
322c0 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
322d0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
322e0 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
322f0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
32300 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
32310 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
32320 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32330 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
32340 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
32350 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
32360 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
32370 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
32380 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
32390 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
323a0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
323b0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
323c0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
323d0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
323e0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
323f0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
32400 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
32410 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
32420 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
32430 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
32440 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
32450 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
32460 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
32470 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
32480 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
32490 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
324a0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
324b0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
324c0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
324d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
324e0 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
324f0 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75  r(S,I,P,T,D) rou
32500 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20  tine causes the 
32510 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  I-th parameter i
32520 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  n.** [prepared s
32530 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68  tatement] S to h
32540 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65  ave an SQL value
32550 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f   of NULL, but to
32560 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f   also be.** asso
32570 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
32580 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70  pointer P of typ
32590 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68  e T.  ^D is eith
325a0 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
325b0 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  r or.** a pointe
325c0 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f  r to a destructo
325d0 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50  r function for P
325e0 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  . ^SQLite will i
325f0 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73  nvoke the.** des
32600 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
32610 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
32620 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73   of P when it is
32630 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a   finished using.
32640 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72  ** P.  The T par
32650 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
32660 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67   a static string
32670 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73  , preferably a s
32680 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c  tring.** literal
32690 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  . The sqlite3_bi
326a0 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75  nd_pointer() rou
326b0 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20  tine is part of 
326c0 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20  the.** [pointer 
326d0 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63  passing interfac
326e0 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c  e] added for SQL
326f0 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a  ite 3.20.0..**.*
32700 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
32710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
32720 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
32730 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
32740 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
32750 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
32760 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
32770 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
32780 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
32790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
327a0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
327b0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
327c0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
327d0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
327e0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
327f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
32800 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
32810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
32820 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
32830 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
32840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
32850 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
32860 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
32870 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
32880 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
32890 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
328a0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
328b0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
328c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
328d0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
328e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
328f0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
32900 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
32910 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
32920 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
32930 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
32940 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
32950 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
32960 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
32970 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
32980 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
32990 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
329a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
329b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
329c0 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
329d0 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
329e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
329f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
32a00 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
32a10 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
32a20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
32a30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
32a40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
32a50 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
32a60 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
32a70 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
32a80 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
32a90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
32aa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
32ab0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
32ac0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
32ad0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32ae0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
32af0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
32b00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
32b10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
32b20 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
32b30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32b40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32b50 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
32b60 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
32b70 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
32b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32b90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
32ba0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
32bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32bc0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
32bd0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
32be0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
32bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32c00 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
32c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
32c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32c30 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
32c40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
32c50 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
32c60 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
32c70 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
32c80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
32c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
32ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
32cb0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
32cc0 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
32cd0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
32ce0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
32cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
32d00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32d10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
32d20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32d30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
32d40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
32d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32d60 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
32d70 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
32d80 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
32d90 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
32da0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
32db0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
32dc0 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
32dd0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
32de0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
32df0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
32e00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32e10 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73  3_bind_pointer(s
32e20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32e30 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  t, void*, const 
32e40 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f  char*,void(*)(vo
32e50 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
32e60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
32e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32e80 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  int, int n);.int
32e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
32ea0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
32eb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
32ec0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f  ite3_uint64);../
32ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
32ee0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
32ef0 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f  ameters.** METHO
32f00 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32f10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
32f20 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
32f30 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
32f40 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
32f50 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
32f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32f70 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
32f80 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
32f90 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
32fa0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
32fb0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
32fc0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
32fd0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
32fe0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
32ff0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
33000 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
33010 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
33020 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
33030 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
33040 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
33050 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
33060 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
33070 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
33080 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
33090 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
330a0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
330b0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
330c0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
330d0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
330e0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
330f0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
33100 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
33110 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
33120 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
33130 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
33140 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33150 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
33160 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
33170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
33180 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
33190 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
331a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
331b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
331c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
331d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
331e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
331f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
33200 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
33210 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44  ameter.** METHOD
33220 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33240 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
33250 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
33260 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
33270 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
33280 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
33290 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
332a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
332b0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
332c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
332d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
332e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
332f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
33300 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
33310 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
33320 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
33330 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
33340 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
33350 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
33360 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
33370 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
33380 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
33390 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
333a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
333b0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
333c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
333d0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
333e0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
333f0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
33400 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
33410 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
33420 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
33430 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
33440 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
33450 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
33460 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
33470 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33480 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
33490 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
334a0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
334b0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
334c0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
334d0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
334e0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
334f0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
33500 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
33510 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
33520 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
33530 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
33540 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
33550 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
33560 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  re16()],.** [sql
33570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
33580 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
33590 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
335a0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
335b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
335c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
335d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
335e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
335f0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
33600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
33610 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
33620 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
33630 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
33640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
33650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33660 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33670 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
33680 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
33690 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
336a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
336b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
336c0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
336d0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
336e0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
336f0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
33700 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
33710 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
33720 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
33730 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
33740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33750 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
33760 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
33770 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
33780 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
33790 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
337a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
337b0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
337c0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
337d0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
337e0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
337f0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
33800 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
33810 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
33820 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
33830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
33840 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
33850 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
33860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
33870 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
33880 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
33890 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
338a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
338b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
338c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
338d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
338e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
338f0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
33900 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
33910 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
33920 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
33930 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
33940 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
33950 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33960 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33970 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
33980 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
33990 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
339a0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
339b0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
339c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
339d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
339e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
339f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
33a00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
33a10 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
33a20 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
33a30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33a40 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
33a50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
33a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33a70 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
33a80 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
33a90 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33aa0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33ab0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
33ac0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33ad0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33ae0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
33af0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
33b00 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69  tement]. ^If thi
33b10 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
33b20 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  s 0, that means 
33b30 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
33b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74  d statement] ret
33b50 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f  urns no data (fo
33b60 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
33b70 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65  DATE])..** ^Howe
33b80 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73  ver, just becaus
33b90 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  e this routine r
33ba0 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76  eturns a positiv
33bb0 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f  e number does no
33bc0 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f  t.** mean that o
33bd0 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ne or more rows 
33be0 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20  of data will be 
33bf0 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45  returned.  ^A SE
33c00 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a  LECT statement.*
33c10 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61  * will always ha
33c20 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71  ve a positive sq
33c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
33c40 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69  nt() but dependi
33c50 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45  ng on the.** WHE
33c60 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
33c70 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61  aints and the ta
33c80 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20  ble content, it 
33c90 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20  might return no 
33ca0 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rows..**.** See 
33cb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
33cc0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
33cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
33ce0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
33cf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33d10 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
33d20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
33d30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33d40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
33d50 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
33d60 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
33d70 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
33d80 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
33d90 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33da0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
33db0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
33dc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
33dd0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
33de0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
33df0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
33e00 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
33e10 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
33e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
33e30 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
33e40 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
33e50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
33e60 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
33e70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
33e80 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
33e90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
33ea0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
33eb0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
33ec0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
33ed0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33ee0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
33ef0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
33f00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
33f10 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
33f20 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
33f30 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
33f40 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
33f50 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
33f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
33f70 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
33f80 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
33f90 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
33fa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
33fb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
33fc0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
33fd0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
33fe0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
33ff0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
34000 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
34010 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
34020 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
34030 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
34040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34050 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
34060 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
34070 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
34080 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
34090 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
340a0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
340b0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
340c0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
340d0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
340e0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
340f0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
34100 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
34120 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
34130 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
34140 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
34150 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
34160 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
34170 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
34180 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
34190 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
341a0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
341b0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
341c0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
341d0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
341e0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
341f0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
34200 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
34210 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
34220 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
34230 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
34240 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
34260 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
34270 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
34280 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
34290 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
342a0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
342b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
342c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
342d0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
342e0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
342f0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
34300 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
34310 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
34320 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
34330 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
34340 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
34350 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
34360 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
34370 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
34380 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
34390 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
343a0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
343b0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
343c0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
343d0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
343e0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
343f0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
34400 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
34410 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
34420 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
34430 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
34440 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
34450 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
34460 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
34470 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
34480 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
34490 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
344a0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
344b0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
344c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
344d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
344e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
344f0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
34500 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
34510 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
34520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34530 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
34540 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
34550 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
34560 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
34570 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
34580 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
34590 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
345a0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
345b0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
345c0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
345d0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
345e0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
345f0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
34600 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34610 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
34620 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
34630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
34640 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
34650 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
34660 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
34670 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
34680 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
34690 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
346a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
346b0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
346c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
346d0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
346e0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
346f0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
34700 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
34710 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
34720 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
34730 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
34740 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
34750 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
34760 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
34770 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
34780 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
34790 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
347a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
347b0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
347c0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
347d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
347e0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
347f0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
34800 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
34810 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
34820 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
34830 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
34840 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
34850 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
34860 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
34870 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
34880 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
34890 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
348a0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
348b0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
348c0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
348d0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
348e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
348f0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
34900 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
34910 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
34920 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
34930 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
34940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
34950 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
34960 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
34970 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
34980 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
34990 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
349a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
349b0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
349c0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
349d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
349e0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
349f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
34a00 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
34a10 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
34a20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
34a30 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
34a40 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
34a50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
34a60 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
34a70 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
34a80 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
34a90 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
34aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34ab0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
34ac0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
34ad0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
34ae0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
34af0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
34b00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
34b10 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
34b20 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
34b30 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
34b40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34b50 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
34b60 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
34b70 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
34b80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34b90 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
34ba0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34bb0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
34bd0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
34be0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
34bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
34c00 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
34c10 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
34c20 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
34c30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34c40 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
34c50 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
34c60 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
34c70 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
34c80 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
34c90 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
34ca0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
34cb0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
34cc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
34cd0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
34ce0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
34cf0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
34d00 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
34d10 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
34d20 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
34d30 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
34d40 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
34d50 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
34d60 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
34d70 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
34d80 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
34d90 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
34da0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
34db0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
34dc0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
34dd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
34de0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
34df0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
34e00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
34e10 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
34e20 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
34e30 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
34e40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
34e50 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
34e60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
34e70 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
34e80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
34e90 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
34ea0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
34eb0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
34ec0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
34ed0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
34ee0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
34ef0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
34f00 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
34f10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
34f20 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
34f30 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
34f40 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
34f50 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
34f60 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
34f70 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
34f80 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
34f90 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
34fa0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
34fb0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
34fc0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
34fd0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
34fe0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
34ff0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
35000 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
35010 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
35020 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
35030 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
35040 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
35050 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
35060 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
35070 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
35080 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
35090 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
350a0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
350b0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
350c0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
350d0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
350e0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
350f0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
35100 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
35110 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
35120 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
35130 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
35140 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
35150 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
35160 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
35170 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
35180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35190 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
351a0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
351b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
351c0 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
351d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
351e0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
351f0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e  repared using an
35200 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y of.** [sqlite3
35210 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
35220 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35230 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
35240 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
35250 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
35260 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
35270 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
35280 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
35290 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
352a0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
352b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
352c0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
352d0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
352e0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
352f0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
35300 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
35310 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
35320 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
35330 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
35340 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
35350 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
35360 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
35370 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
35380 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
35390 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
353a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
353b0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
353c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
353d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
353e0 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a  pare16_v3()],.**
353f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35400 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
35410 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
35420 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
35430 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
35440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
35450 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
35460 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
35470 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  w "vX" interface
35480 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
35490 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
354a0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
354b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
354c0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
354d0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
354e0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
354f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
35500 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35510 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
35520 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
35530 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
35540 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
35550 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
35560 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
35570 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
35580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
35590 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
355a0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
355b0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
355c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
355d0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
355e0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
355f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
35600 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
35610 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
35620 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
35630 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
35640 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
35650 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
35660 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
35670 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
35680 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
35690 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
356a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
356b0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
356c0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
356d0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
356e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
356f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
35700 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
35710 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
35720 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
35730 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
35740 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
35750 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
35760 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
35770 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
35780 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
35790 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
357a0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
357b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
357c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
357d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
357e0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
357f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
35800 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
35810 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
35820 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
35830 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
35840 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
35850 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
35860 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
35870 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
35880 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
35890 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
358a0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
358b0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
358c0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
358d0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
358e0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
358f0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
35900 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
35910 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
35920 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
35930 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
35940 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
35950 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
35960 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
35970 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
35980 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
35990 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
359a0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
359b0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
359c0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
359d0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
359e0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
359f0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
35a00 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
35a10 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
35a20 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
35a30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
35a40 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
35a50 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
35a60 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
35a70 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
35a80 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
35a90 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
35aa0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
35ab0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
35ac0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
35ad0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
35ae0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
35af0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
35b00 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
35b10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
35b20 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
35b30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
35b40 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
35b50 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
35b60 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
35b70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
35b80 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
35b90 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
35ba0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
35bb0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
35bc0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
35bd0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
35be0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
35bf0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
35c00 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
35c10 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
35c20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
35c30 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
35c40 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
35c50 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
35c60 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
35c70 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
35c80 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
35c90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
35ca0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
35cb0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
35cc0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
35cd0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
35ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
35cf0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
35d00 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
35d10 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
35d20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
35d30 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
35d40 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
35d50 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
35d60 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
35d70 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
35d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
35d90 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
35da0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
35db0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
35dc0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
35dd0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
35de0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
35df0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
35e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
35e10 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
35e20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
35e30 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
35e40 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
35e50 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
35e60 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
35e70 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
35e80 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
35e90 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
35ea0 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
35eb0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
35ec0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
35ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
35ee0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
35ef0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35f00 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
35f10 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
35f20 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
35f30 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
35f40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
35f50 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
35f60 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
35f70 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
35f80 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
35f90 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
35fa0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
35fb0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
35fc0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
35fd0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
35fe0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
35ff0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
36000 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
36010 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
36020 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
36030 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
36040 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
36050 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
36060 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
36070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
36080 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
36090 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
360a0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
360b0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
360c0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
360d0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
360e0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
360f0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
36100 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
36110 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
36120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36130 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
36140 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
36150 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
36160 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
36170 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
36180 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
36190 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
361a0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
361b0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
361c0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
361d0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
361e0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
361f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
36200 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
36210 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
36220 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
36230 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
36240 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72  prepare_v3()] or
36250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
36260 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  e_v2()].** or [s
36270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
36280 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
36290 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
362a0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
362b0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
362c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
362d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
362e0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
362f0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
36300 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
36310 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
36320 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
36330 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
36340 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
36350 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69  se of the "vX" i
36360 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63  nterfaces is rec
36370 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
36380 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
36390 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
363a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
363b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
363c0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
363d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
363e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
363f0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
36400 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
36410 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
36420 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
36430 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
36440 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
36450 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
36460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36470 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
36480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
36490 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
364a0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
364b0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
364c0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
364d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
364e0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
364f0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
36500 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
36510 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
36520 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
36530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
36540 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
36550 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
36560 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
36570 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
36580 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
36590 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
365a0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
365b0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
365c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
365d0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
365e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
365f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
36600 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
36610 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
36620 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
36630 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36640 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
36650 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
36660 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
36670 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
36680 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
36690 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
366a0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
366b0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
366c0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
366d0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
366e0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
366f0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
36700 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36710 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
36720 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
36730 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
36740 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
36750 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
36760 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
36770 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
36780 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
36790 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
367a0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
367b0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
367c0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
367d0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
367e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
367f0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
36800 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
36810 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
36820 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
36830 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
36840 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
36850 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
36860 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
36870 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
36880 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
36890 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
368a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
368b0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
368c0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
368d0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
368e0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
368f0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
36900 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
36910 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
36920 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
36930 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
36940 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
36950 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
36960 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
36970 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
36980 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
36990 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
369a0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
369b0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
369c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
369d0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
369e0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
369f0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
36a00 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
36a10 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
36a20 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
36a30 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
36a40 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
36a50 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
36a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36a70 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
36a80 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
36a90 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
36aa0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
36ab0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
36ac0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
36ad0 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a  <b>Summary:</b>.
36ae0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
36af0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63  table border=0 c
36b00 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c  ellpadding=0 cel
36b10 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c  lspacing=0>.** <
36b20 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36b30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62  3_column_blob</b
36b40 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42  ><td>&rarr;<td>B
36b50 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  LOB result.** <t
36b60 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36b70 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f  _column_double</
36b80 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36b90 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  REAL result.** <
36ba0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36bb0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e  3_column_int</b>
36bc0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32  <td>&rarr;<td>32
36bd0 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
36be0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
36bf0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36c00 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72  _int64</b><td>&r
36c10 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49  arr;<td>64-bit I
36c20 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a  NTEGER result.**
36c30 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c  te3_column_text<
36c50 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36c60 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75  >UTF-8 TEXT resu
36c70 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
36c80 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36c90 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72  text16</b><td>&r
36ca0 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54  arr;<td>UTF-16 T
36cb0 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EXT result.** <t
36cc0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36cd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62  _column_value</b
36ce0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54  ><td>&rarr;<td>T
36cf0 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20  he result as an 
36d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
36d10 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73  ue|unprotected s
36d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36d30 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ject..** <tr><td
36d40 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
36d50 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c  ;<td>&nbsp;.** <
36d60 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36d70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f  3_column_bytes</
36d80 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36d90 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a  Size of a BLOB.*
36da0 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58  * or a UTF-8 TEX
36db0 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65  T result in byte
36dc0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  s.** <tr><td><b>
36dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36de0 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73  ytes16&nbsp;&nbs
36df0 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72  p;</b>.** <td>&r
36e00 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  arr;&nbsp;&nbsp;
36e10 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d  <td>Size of UTF-
36e20 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79  16.** TEXT in by
36e30 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  tes.** <tr><td><
36e40 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36e50 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  _type</b><td>&ra
36e60 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a  rr;<td>Default.*
36e70 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  * datatype of th
36e80 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61  e result.** </ta
36e90 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  ble></blockquote
36ea0 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69  >.**.** <b>Detai
36eb0 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54  ls:</b>.**.** ^T
36ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
36ed0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
36ee0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
36ef0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
36f00 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
36f10 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
36f20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
36f30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
36f40 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
36f50 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
36f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
36f70 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
36f80 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
36f90 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
36fa0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
36fb0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
36fc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
36fd0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
36fe0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
36ff0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
37000 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
37010 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
37020 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
37030 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
37040 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
37050 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
37060 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
37070 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
37080 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
37090 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
370a0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
370b0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
370c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
370d0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
370e0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
370f0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
37100 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
37110 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
37120 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
37130 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
37140 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
37150 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
37160 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
37170 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
37180 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
37190 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
371a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
371b0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
371c0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
371d0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
371e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
371f0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
37200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
37210 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
37220 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
37230 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
37240 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
37250 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
37260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
37270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
37280 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
37290 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
372a0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
372b0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
372c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
372d0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
372e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
372f0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
37300 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
37310 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
37320 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37330 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
37340 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
37350 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
37360 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
37370 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
37380 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
37390 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
373a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
373b0 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66  first six interf
373c0 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f  aces (_blob, _do
373d0 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74  uble, _int, _int
373e0 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f  64, _text, and _
373f0 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20  text16).** each 
37400 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65  return the value
37410 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
37420 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69  umn in a specifi
37430 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20  c data format.  
37440 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  If.** the result
37450 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69   column is not i
37460 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20  nitially in the 
37470 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74  requested format
37480 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
37490 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72  * if the query r
374a0 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
374b0 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65  r but the sqlite
374c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
374d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
374e0 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20  used to extract 
374f0 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20  the value) then 
37500 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70  an automatic typ
37510 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
37520 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a  performed..**.**
37530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
37540 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
37550 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
37560 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
37570 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
37580 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
37590 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
375a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
375b0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
375c0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
375d0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
375e0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
375f0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
37600 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
37610 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
37620 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68  ITE_NULL]..** Th
37630 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37640 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
37650 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75  _type() can be u
37660 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68  sed to decide wh
37670 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69  ich.** of the fi
37680 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63  rst six interfac
37690 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64  e should be used
376a0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
376b0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a  column value..**
376c0 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
376d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
376e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
376f0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
37700 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74  if no.** automat
37710 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
37720 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
37730 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20  d for the value 
37740 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a  in question.  .*
37750 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63  * After a type c
37760 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72  onversion, the r
37770 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67  esult of calling
37780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37790 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  type().** is und
377a0 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68  efined, though h
377b0 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65  armless.  Future
377c0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
377d0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
377e0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
377f0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
37800 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
37810 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
37820 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
37830 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
37840 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20   BLOB or a TEXT 
37850 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  string, then the
37860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37870 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71  bytes().** or sq
37880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37890 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  es16() interface
378a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
378b0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
378c0 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42  ize.** of that B
378d0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
378e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
378f0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
37900 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
37910 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
37920 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
37930 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37940 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
37950 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
37960 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
37970 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37980 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
37990 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
379a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
379b0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
379c0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
379d0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
379e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
379f0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
37a00 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
37a10 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
37a20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37a30 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
37a40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
37a50 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
37a60 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
37a70 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
37a80 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
37a90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
37aa0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
37ab0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
37ac0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
37ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37ae0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
37af0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
37b00 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
37b10 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
37b20 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
37b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37b40 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
37b50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37b60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
37b70 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
37b80 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
37b90 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
37ba0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
37bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37bc0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
37bd0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
37be0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
37bf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37c00 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
37c10 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
37c20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
37c30 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
37c40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
37c50 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
37c60 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
37c70 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
37c80 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
37c90 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
37ca0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
37cb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
37cc0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
37cd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
37ce0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
37cf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37d00 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
37d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
37d20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
37d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37d40 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
37d50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37d60 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
37d70 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
37d80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
37d90 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
37da0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
37db0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
37dc0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
37dd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
37de0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
37df0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
37e00 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
37e10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
37e20 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
37e30 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
37e40 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
37e50 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
37e60 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
37e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37e80 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
37e90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
37ea0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
37eb0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
37ec0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
37ed0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
37ee0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
37ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37f00 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
37f10 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
37f20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37f30 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e  .**.** <b>Warnin
37f40 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65  g:</b> ^The obje
37f50 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
37f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
37f70 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
37f80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37f90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37fa0 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69  ect.  In a multi
37fb0 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e  threaded environ
37fc0 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72  ment,.** an unpr
37fd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37fe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
37ff0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61   only be used sa
38000 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71  fely with.** [sq
38010 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
38020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38030 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
38040 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
38050 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
38060 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
38070 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
38080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
38090 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
380a0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
380b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
380c0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
380d0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
380e0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
380f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
38100 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
38110 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
38120 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ], the behavior 
38130 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
38140 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65  e..** Hence, the
38150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
38160 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
38170 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  e.** is normally
38180 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74   only useful wit
38190 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hin the implemen
381a0 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61  tation of .** [a
381b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
381c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
381d0 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  ] or [virtual ta
381e0 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69  bles], not withi
381f0 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61  n.** top-level a
38200 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e  pplication code.
38210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65  .**.** The these
38220 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74   routines may at
38230 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
38240 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66   the datatype of
38250 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
38260 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  ^For example, if
38270 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
38280 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
38290 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
382a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
382b0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
382c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
382d0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
382e0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
382f0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
38300 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
38310 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
38320 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
38330 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
38340 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
38350 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
38360 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
38370 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
38380 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
38390 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
383a0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
383b0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
383c0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
383d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
383e0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
383f0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
38400 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
38410 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
38420 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
38430 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
38440 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
38450 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
38460 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
38470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
38480 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
38490 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
384a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
384b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
384c0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
384d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
384e0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
384f0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
38500 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
38510 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
38520 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
38530 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
38540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
38550 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
38560 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
38570 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
38580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
38590 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
385a0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
385b0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
385c0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
385d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
385e0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
385f0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
38600 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
38610 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
38620 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
38630 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
38640 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
38650 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
38660 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
38670 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
38680 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
38690 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
386a0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
386b0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
386c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
386d0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
386e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
386f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
38700 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
38710 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
38720 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  >