SQLite Android Bindings
Hex Artifact Content
Not logged in

Artifact 3c500252ee2921d0e7548ab05365f3d3bf90b0f7:


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 33 2e 32 39 2e 30 22 0a 23 64 65      "3.29.0".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 39 30  ION_NUMBER 30290
1230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 39 2d 30 37 2d 31 30 20 31 37 3a   "2019-07-10 17:
1260: 33 32 3a 30 33 20 66 63 38 32 62 37 33 65 61 61  32:03 fc82b73eaa
1270: 63 38 62 33 36 39 35 30 65 35 32 37 66 31 32 63  c8b36950e527f12c
1280: 34 62 35 64 63 31 65 31 34 37 65 36 66 34 61 64  4b5dc1e147e6f4ad
1290: 32 32 31 37 61 65 34 33 61 64 38 32 38 38 32 61  2217ae43ad82882a
12a0: 38 38 62 66 61 36 22 0a 0a 2f 2a 0a 2a 2a 20 43  88bfa6"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  );.#else.# defin
1e80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1e90: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 58 29 20  eoption_used(X) 
1ea0: 30 0a 23 20 64 65 66 69 6e 65 20 73 71 6c 69 74  0.# define sqlit
1eb0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ec0: 5f 67 65 74 28 58 29 20 20 28 28 76 6f 69 64 2a  _get(X)  ((void*
1ed0: 29 30 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  )0).#endif../*.*
1ee0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
1ef0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
1f00: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
1f10: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  safe.**.** ^The 
1f20: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1f30: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  fe() function re
1f40: 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e  turns zero if an
1f50: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c  d only if.** SQL
1f60: 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ite was compiled
1f70: 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63   with mutexing c
1f80: 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20  ode omitted due 
1f90: 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  to the.** [SQLIT
1fa0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f  E_THREADSAFE] co
1fb0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1fc0: 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30  n being set to 0
1fd0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  ..**.** SQLite c
1fe0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1ff0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
2000: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
2010: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
2020: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
2030: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
2040: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
2050: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
2060: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
2070: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
2080: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
2090: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20a0: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
20b0: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
20c0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
20d0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
20e0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
20f0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
2100: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
2110: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
2120: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
2130: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
2140: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
2150: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
2160: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
2170: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
2180: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
2190: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
21a0: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
21b0: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
21c0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
21d0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
21e0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nabled..** ^The 
21f0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
2200: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
2210: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
2220: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2230: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2240: 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  by an applicatio
2250: 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  n to make sure t
2260: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
2270: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
2280: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
2290: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
22a0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
22b0: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
22c0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
22d0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
22e0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
22f0: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
2300: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
2310: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
2320: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
2330: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2340: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
2350: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2360: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
2370: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72  _THREADSAFE=1 or
2380: 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73   =2 then mutexes
2390: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
23a0: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63  default but.** c
23b0: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70  an be fully or p
23c0: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65  artially disable
23d0: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  d using a call t
23e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
23f0: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65  g()].** with the
2400: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43   verbs [SQLITE_C
2410: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2420: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  AD], [SQLITE_CON
2430: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2440: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2450: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
2460: 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72  D].  ^(The retur
2470: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a  n value of the.*
2480: 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  * sqlite3_thread
2490: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
24a0: 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63  shows only the c
24b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
24c0: 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64  ing of.** thread
24d0: 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79   safety, not any
24e0: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
24f0: 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  s to that settin
2500: 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c  g made by.** sql
2510: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49  ite3_config(). I
2520: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2530: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2540: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72  from sqlite3_thr
2550: 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20  eadsafe().** is 
2560: 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c  unchanged by cal
2570: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2580: 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  nfig().)^.**.** 
2590: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
25a0: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
25b0: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
25c0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25d0: 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
25e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72   int sqlite3_thr
25f0: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2600: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2610: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2620: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2630: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2640: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2650: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2660: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2670: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2680: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
2690: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
26a0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
26b0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
26c0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
26d0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
26e0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
26f0: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2700: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2710: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2720: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2730: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2760: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2770: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2780: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
2790: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
27a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
27b0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
27c0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
27d0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
27e0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
27f0: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2800: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2810: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2820: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2830: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2840: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2850: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2860: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2870: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2880: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
2890: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28a0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
28b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
28c0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
28d0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
28e0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
28f0: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2900: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2910: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2920: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2930: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2940: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2950: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2960: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2970: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2980: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
2990: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
29a0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
29b0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
29c0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
29d0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
29e0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
29f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2a00: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2a10: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2a20: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2a30: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2a40: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2a50: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2a60: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2a70: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2a80: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
2a90: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
2aa0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
2ab0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
2ac0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2ad0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2ae0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2af0: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2b00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2b10: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2b20: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2b30: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2b40: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2b50: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2b60: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef 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 69 6e 74 36 34 3b 0a 23 20 69 66 64 65  te_int64;.# ifde
2b90: 66 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f  f SQLITE_UINT64_
2ba0: 54 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66  TYPE.    typedef
2bb0: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2bc0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2bd0: 34 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20  4;.# else  .    
2be0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2bf0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2c00: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2c10: 3b 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20  ;.# endif.#elif 
2c20: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
2c30: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
2c40: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
2c50: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
2c60: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2c70: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2c90: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
2ca0: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
2cb0: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
2cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2cd0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
2ce0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
2cf0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
2d00: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2d10: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
2d20: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
2d30: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
2d40: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
2d50: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
2d60: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
2d70: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2d80: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
2d90: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
2da0: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
2db0: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
2dc0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
2dd0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
2de0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2df0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
2e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
2e10: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
2e20: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44   Connection.** D
2e30: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
2e40: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
2e50: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2e60: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2e70: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2e80: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2e90: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2ea0: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2eb0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2ec0: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2ed0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2ee0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2ef0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ] if.** the [sql
2f00: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
2f10: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2f20: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2f30: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
2f40: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
2f50: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
2f60: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2f70: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
2f80: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
2f90: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
2fa0: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
2fb0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2fc0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
2fd0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
2fe0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
2ff0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
3000: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
3010: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
3020: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
3030: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
3040: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
3050: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
3060: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
3070: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f  tements.** and/o
3080: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
3090: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68  ite3_backups, th
30a0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
30b0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d  connection becom
30c0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c  es.** an unusabl
30d0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68  e "zombie" which
30e0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
30f0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  lly be deallocat
3100: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ed when the.** l
3110: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
3120: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
3130: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20  zed or the last 
3140: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69  sqlite3_backup i
3150: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20  s.** finished.  
3160: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
3170: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
3180: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
3190: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73   use with.** hos
31a0: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74  t languages that
31b0: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c   are garbage col
31c0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72  lected, and wher
31d0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  e the order in w
31e0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74  hich.** destruct
31f0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69  ors are called i
3200: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a  s arbitrary..**.
3210: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
3220: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
3230: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
3240: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
3250: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a  ed statements],.
3260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
3270: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
3280: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
3290: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  s], and .** [sql
32a0: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69  ite3_backup_fini
32b0: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c  sh | finish] all
32c0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
32d0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69  ] objects associ
32e0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
32f0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3300: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
3310: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
3320: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a  he object.  ^If.
3330: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ** sqlite3_close
3340: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
3350: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
3360: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
3370: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
3380: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
3390: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33a0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
33b0: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  and/or.** [sqlit
33c0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
33d0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ts then it retur
33e0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61  ns [SQLITE_OK] a
33f0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74  nd the deallocat
3400: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72  ion.** of resour
3410: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20  ces is deferred 
3420: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61  until all [prepa
3430: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3440: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3450: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
3460: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
3470: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f   are also destro
3480: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  yed..**.** ^If a
3490: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
34a0: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ct is destroyed 
34b0: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74  while a transact
34c0: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20  ion is open,.** 
34d0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
34e0: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
34f0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
3500: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65  .** The C parame
3510: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3520: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73  close(C)] and [s
3530: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
3540: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  C)].** must be e
3550: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
3560: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
3570: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3580: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
3590: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
35a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
35b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
35c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
35d0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
35e0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
35f0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  ed..** ^Calling 
3600: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
3610: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  or sqlite3_close
3620: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
3630: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67  L pointer.** arg
3640: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c  ument is a harml
3650: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
3660: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3670: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
3680: 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
3690: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
36a0: 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b  se_v2(sqlite3*);
36b0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
36c0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
36d0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
36e0: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
36f0: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
3700: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
3710: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
3720: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
3730: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
3740: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
3750: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
3760: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3770: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
3780: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3790: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
37a0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
37b0: 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  face.** METHOD: 
37c0: 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
37d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
37e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
37f0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
3800: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
3810: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
3820: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
3830: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
3840: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
3850: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
3860: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
3870: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
3880: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
3890: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
38a0: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
38b0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
38c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38d0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
38e0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
38f0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
3900: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
3910: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
3920: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
3930: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
3940: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
3950: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
3960: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3970: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
3980: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
3990: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
39a0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
39b0: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
39c0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
39d0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
39e0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
39f0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
3a00: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
3a10: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
3a20: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
3a30: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
3a40: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3a50: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3a60: 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20  ec() is relayed 
3a70: 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31  through to the 1
3a80: 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65  st argument of e
3a90: 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ach.** callback 
3aa0: 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66  invocation.  ^If
3ab0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f   the callback po
3ac0: 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
3ad0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55  _exec().** is NU
3ae0: 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c  LL, then no call
3af0: 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76  back is ever inv
3b00: 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20  oked and result 
3b10: 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f  rows are.** igno
3b20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  red..**.** ^If a
3b30: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
3b40: 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
3b50: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
3b60: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  ts passed into.*
3b70: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3b80: 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e  , then execution
3b90: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
3ba0: 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20  statement stops 
3bb0: 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  and.** subsequen
3bc0: 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  t statements are
3bd0: 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74   skipped.  ^If t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3c00: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ().** is not NUL
3c10: 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72  L then any error
3c20: 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74   message is writ
3c30: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
3c40: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3c50: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3c60: 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62  ()] and passed b
3c70: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20  ack through the 
3c80: 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  5th parameter..*
3c90: 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72  * To avoid memor
3ca0: 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70  y leaks, the app
3cb0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
3cc0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
3cd0: 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72  free()].** on er
3ce0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3cf0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72  ngs returned thr
3d00: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3d10: 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c  ameter of.** sql
3d20: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3d30: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
3d40: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
3d50: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3d60: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
3d70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3d80: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3d90: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3da0: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3db0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3dc0: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3dd0: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3de0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3df0: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3e00: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3e10: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3e20: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3e30: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
3e40: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e50: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
3e60: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
3e70: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
3e80: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
3e90: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3ea0: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3eb0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3ec0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3ed0: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3ee0: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3ef0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3f00: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3f10: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3f20: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3f30: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
3f40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3f50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f60: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
3f70: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3f80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
3f90: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3fa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3fb0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3fc0: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3fd0: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3fe0: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3ff0: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
4000: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
4010: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
4020: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
4030: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
4040: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
4050: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
4060: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
4070: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
4080: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
4090: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
40a0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
40b0: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
40c0: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
40d0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
40e0: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
40f0: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
4100: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
4110: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
4120: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
4130: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4140: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
4150: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
4160: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
4170: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
4180: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
4190: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
41a0: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
41b0: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
41c0: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
41d0: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
41e0: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
41f0: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
4200: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
4210: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
4220: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
4230: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
4240: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
4250: 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
4260: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4270: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
4280: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
4290: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
42a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
42b0: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
42c0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
42d0: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64  not close the [d
42e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
42f0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
4300: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
4310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4320: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4330: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4340: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4350: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4360: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
4370: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
4380: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
4390: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
43a0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
43b0: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
43c0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
43d0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
43e0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
43f0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
4400: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
4410: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
4420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4430: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
4440: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4450: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4460: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4470: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4480: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4490: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
44a0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
44b0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
44c0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
44d0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
44e0: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
44f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4500: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
4510: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
4520: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
4530: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
4540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4550: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4560: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4570: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4580: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4590: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
45a0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
45b0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
45c0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
45d0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
45e0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
45f0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4600: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4610: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4620: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4630: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4640: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4650: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4660: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4670: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4680: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4690: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
46a0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
46b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46c0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
46d0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
46e0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
46f0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4700: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4710: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4720: 20 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65       1   /* Gene
4730: 72 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  ric error */.#de
4740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4750: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4760: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4770: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
47a0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
47b0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
47c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47d0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
47e0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
47f0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4800: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4820: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4830: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4840: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4860: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4870: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4880: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
48b0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
48c0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
48e0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
48f0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4900: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4910: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4920: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4930: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4940: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4950: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4960: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4970: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4980: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4990: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
49a0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
49b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49c0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
49d0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
49e0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
49f0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4a20: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4a30: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4a40: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4a60: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4a70: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4a80: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4a90: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4ab0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4ac0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4ad0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4ae0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4af0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
4b00: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
4b10: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4b20: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4b30: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4b40: 20 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72     16   /* Inter
4b50: 6e 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a  nal use only */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4b70: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4b80: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4b90: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4ba0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4bb0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4bc0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4bd0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4be0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4bf0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4c00: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4c10: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4c20: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4c30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c40: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4c50: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4c60: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4c70: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4c80: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4c90: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4ca0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4cb0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4cc0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4cd0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4ce0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4cf0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4d00: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4d10: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4d20: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4d30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4d40: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4d50: 20 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f    /* Not used */
4d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d70: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4d80: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4d90: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4da0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4db0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4dc0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4dd0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4de0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
4df0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4e10: 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20  OTICE      27   
4e20: 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73  /* Notifications
4e30: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4e40: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4e50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20  QLITE_WARNING   
4e60: 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e    28   /* Warnin
4e70: 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  gs from sqlite3_
4e80: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
4e90: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4ea0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4eb0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4ec0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4ed0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ee0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4ef0: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4f00: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
4f10: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
4f20: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
4f30: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
4f40: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4f50: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
4f60: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4f70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f80: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4f90: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
4fa0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
4fb0: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
4fc0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
4fd0: 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72  ne of 30 integer
4fe0: 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  .** [result code
4ff0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
5000: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
5010: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
5020: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
5030: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
5040: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
5050: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
5060: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
5070: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
5080: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
5090: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
50a0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
50b0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
50c0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
50d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
50e0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64  version 3.3.8 [d
50f0: 61 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20  ateof:3.3.8].** 
5100: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
5110: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
5120: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
5130: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
5140: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
5150: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
5160: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
5170: 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65  . These [extende
5180: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
5190: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
51a0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
51b0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
51c0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
51d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
51e0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
51f0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
5200: 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e  .  Or, the exten
5210: 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20  ded code for.** 
5220: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
5230: 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74  error can be obt
5240: 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  ained using.** [
5250: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
5260: 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a  _errcode()]..*/.
5270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
5280: 52 52 4f 52 5f 4d 49 53 53 49 4e 47 5f 43 4f 4c  RROR_MISSING_COL
5290: 4c 53 45 51 20 20 20 28 53 51 4c 49 54 45 5f 45  LSEQ   (SQLITE_E
52a0: 52 52 4f 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RROR | (1<<8)).#
52b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
52c0: 52 4f 52 5f 52 45 54 52 59 20 20 20 20 20 20 20  ROR_RETRY       
52d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52        (SQLITE_ER
52e0: 52 4f 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ROR | (2<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
5300: 4f 52 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  OR_SNAPSHOT     
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52       (SQLITE_ERR
5320: 4f 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  OR | (3<<8)).#de
5330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5340: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
5350: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5360: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5400: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5420: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5440: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
5480: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
54c0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
5500: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
5520: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5530: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5540: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5550: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
5560: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5570: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
5580: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5590: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
55a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55b0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
55c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
55e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55f0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
5600: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5610: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
5620: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5630: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5640: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5650: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
5680: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
5690: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
56a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56b0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
56c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
56e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56f0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
5700: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5710: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
5720: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5730: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
5740: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
5750: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5760: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5770: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5780: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5790: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
57a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57b0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
57c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
57e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57f0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
5800: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5810: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
5820: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5830: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
5840: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5850: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5860: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5870: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5880: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5890: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
58a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58b0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
58c0: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
58d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
5900: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5910: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
5920: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5930: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
5940: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5950: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
5960: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5970: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
5980: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
5990: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
59a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59b0: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
59c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
59d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
59e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59f0: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
5a00: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5a10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
5a20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a30: 54 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f 41  TE_IOERR_BEGIN_A
5a40: 54 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c 49  TOMIC      (SQLI
5a50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c 3c  TE_IOERR | (29<<
5a60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a70: 54 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f  TE_IOERR_COMMIT_
5a80: 41 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c 49  ATOMIC     (SQLI
5a90: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c 3c  TE_IOERR | (30<<
5aa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ab0: 54 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41 43  TE_IOERR_ROLLBAC
5ac0: 4b 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c 49  K_ATOMIC   (SQLI
5ad0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c 3c  TE_IOERR | (31<<
5ae0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5af0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5b00: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5b10: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 4c 4f 43 4b 45 44 5f 56 54 41 42 20  ITE_LOCKED_VTAB 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5b50: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 32  ITE_LOCKED |  (2
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5b80: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5b90: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5ba0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5bb0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
5bc0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
5bd0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5be0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c00: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5c10: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c30: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5c40: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5c50: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5c60: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5c70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5c80: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5c90: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5ca0: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
5cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5cc0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
5cd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5ce0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
5cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5d00: 41 4e 54 4f 50 45 4e 5f 44 49 52 54 59 57 41 4c  ANTOPEN_DIRTYWAL
5d10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d20: 41 4e 54 4f 50 45 4e 20 7c 20 28 35 3c 3c 38 29  ANTOPEN | (5<<8)
5d30: 29 20 2f 2a 20 4e 6f 74 20 55 73 65 64 20 2a 2f  ) /* Not Used */
5d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d50: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d70: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5d80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d90: 5f 43 4f 52 52 55 50 54 5f 53 45 51 55 45 4e 43  _CORRUPT_SEQUENC
5da0: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  E        (SQLITE
5db0: 5f 43 4f 52 52 55 50 54 20 7c 20 28 32 3c 3c 38  _CORRUPT | (2<<8
5dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5dd0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5de0: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5df0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5e00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e10: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5e20: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5e30: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5e40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5e50: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5e60: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
5e70: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5e80: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5e90: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5ea0: 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20  _DBMOVED        
5eb0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5ec0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5ed0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5ee0: 4c 59 5f 43 41 4e 54 49 4e 49 54 20 20 20 20 20  LY_CANTINIT     
5ef0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5f00: 4c 59 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  LY | (5<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5f20: 4f 4e 4c 59 5f 44 49 52 45 43 54 4f 52 59 20 20  ONLY_DIRECTORY  
5f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5f40: 4f 4e 4c 59 20 7c 20 28 36 3c 3c 38 29 29 0a 23  ONLY | (6<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5f60: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
5f80: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
5f90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
5fb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5fc0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5fd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5ff0: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
6000: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
6010: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6030: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
6040: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6050: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
6060: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6070: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
6080: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6090: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
60a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
60b0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
60c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60d0: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
60e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
6100: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
6110: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
6120: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6140: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
6150: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6160: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
6170: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6180: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
6190: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
61a0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
61b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
61c0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
61d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
61e0: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
61f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6200: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
6210: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
6220: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
6230: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6240: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
6250: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
6260: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
6270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6280: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
6290: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
62a0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
62b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
62c0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
62d0: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
62e0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
62f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
6300: 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20  QLITE_AUTH_USER 
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
6320: 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c  QLITE_AUTH | (1<
6330: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6340: 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d  ITE_OK_LOAD_PERM
6350: 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 4c  ANENTLY     (SQL
6360: 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29  ITE_OK | (1<<8))
6370: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6380: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
6390: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
63a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
63b0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
63c0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
63d0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
63e0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
6400: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
6410: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
6420: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
6430: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6440: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
6450: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6460: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
6470: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
6480: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6490: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
64a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
64b0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
64c0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
64d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
64e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
64f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6500: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
6510: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
6520: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6530: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6540: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6550: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
6560: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
6570: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6580: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6590: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
65a0: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
65b0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
65c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
65d0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
65e0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
65f0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6600: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6610: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
6620: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
6630: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6640: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6650: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6660: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
6670: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
6680: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6690: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
66a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
66b0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
66c0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
66d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
66e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
66f0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
6700: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
6710: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6720: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6730: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
6740: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
6750: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6760: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6770: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
6780: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
6790: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
67a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
67b0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
67c0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
67d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
67e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
67f0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
6800: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
6810: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6820: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6830: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
6840: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
6850: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6860: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6870: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
6880: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
6890: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
68a0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
68b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
68c0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
68d0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
68e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
68f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6900: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6910: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6920: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6930: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6940: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6950: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6960: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6970: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6980: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6990: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
69a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
69b0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
69c0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
69d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
69e0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a00: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
6a10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6a20: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6a30: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6a40: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6a50: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6a60: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6a70: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6a80: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6a90: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6aa0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6ab0: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
6ac0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
6ad0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
6ae0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
6af0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
6b00: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
6b10: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6b20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6b30: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6b40: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6b50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6b60: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6b70: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6b80: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6b90: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6ba0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6bb0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6bc0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6bd0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6be0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6bf0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6c00: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6c10: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6c20: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6c30: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6c40: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6c50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6c60: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6c70: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6c80: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6c90: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6ca0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6cb0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6cc0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6cd0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6ce0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6cf0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6d00: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6d10: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6d20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6d30: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6d40: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6d50: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6d60: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6d70: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6d80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6d90: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6da0: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6db0: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
6dc0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
6dd0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
6de0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
6df0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
6e00: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
6e10: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6e20: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6e30: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6e40: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6e50: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6e60: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6e70: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6e80: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6e90: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6ea0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6eb0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6ec0: 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61  WHEN_OPEN.** fla
6ed0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6ee0: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
6ef0: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
6f00: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
6f10: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6f20: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
6f30: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
6f40: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
6f50: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
6f60: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
6f70: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
6f80: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
6f90: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
6fa0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6fb0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
6fc0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6fd0: 73 20 74 68 61 74 20 74 68 65 20 75 6e 64 65 72  s that the under
6fe0: 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65 73 79 73  lying.** filesys
6ff0: 74 65 6d 20 73 75 70 70 6f 72 74 73 20 64 6f 69  tem supports doi
7000: 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77 72 69 74  ng multiple writ
7010: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 74 6f  e operations ato
7020: 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f  mically when tho
7030: 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72  se.** write oper
7040: 61 74 69 6f 6e 73 20 61 72 65 20 62 72 61 63 6b  ations are brack
7050: 65 74 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f  eted by [SQLITE_
7060: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
7070: 49 43 5f 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a  IC_WRITE] and.**
7080: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
7090: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
70a0: 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  TE]..*/.#define 
70b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
70c0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
70d0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
70e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
70f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
7100: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7110: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7120: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7130: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
7140: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
7150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7160: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
7170: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7180: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
7190: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
71a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
71b0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
71c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
71d0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
71e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
71f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7200: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7220: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
7230: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7240: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
7250: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
7260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7270: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
7280: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7290: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
72c0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
72d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
72e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
72f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7300: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
7310: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
7320: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
7330: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
7340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7350: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
7360: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
7370: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7380: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
7390: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
73a0: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e  x00002000.#defin
73b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42  e SQLITE_IOCAP_B
73c0: 41 54 43 48 5f 41 54 4f 4d 49 43 20 20 20 20 20  ATCH_ATOMIC     
73d0: 20 20 20 20 20 20 30 78 30 30 30 30 34 30 30 30        0x00004000
73e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
73f0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
7400: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
7410: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
7420: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
7430: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7440: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
7450: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
7460: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
7470: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
7480: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
7490: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74a0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
74b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
74c0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
74d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
74e0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
74f0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
7500: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7510: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
7520: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
7530: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
7540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7550: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
7560: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7570: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
7580: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
7590: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
75a0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
75b0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
75c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
75d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
75e0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
75f0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
7600: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7610: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
7620: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
7630: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
7640: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
7650: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
7660: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
7670: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
7680: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
7690: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
76a0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
76b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
76c0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
76d0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
76e0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
76f0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
7700: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7710: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
7720: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
7730: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
7740: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
7750: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
7760: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7770: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
7780: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7790: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
77a0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
77b0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
77c0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
77d0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
77e0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
77f0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
7800: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
7810: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
7820: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
7830: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
7840: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
7850: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
7860: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
7870: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
7880: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7890: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
78a0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
78b0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
78c0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
78d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
78e0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
78f0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
7900: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
7910: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
7920: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
7930: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
7940: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7950: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7960: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7970: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7980: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7990: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
79a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
79b0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
79c0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
79d0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
79e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
79f0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7a00: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
7a10: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
7a20: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
7a30: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
7a40: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7a50: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7a60: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7a70: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7a80: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7a90: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7aa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
7ab0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
7ac0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
7ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7ae0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
7af0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
7b00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7b10: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
7b20: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
7b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7b40: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7b50: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7b60: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7b70: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7b80: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7b90: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7ba0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
7bb0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
7bc0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
7bd0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
7be0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
7bf0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
7c00: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
7c10: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
7c20: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
7c30: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
7c40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7c50: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7c60: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7c70: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7c80: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7c90: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7ca0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7cb0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
7cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
7cd0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7ce0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
7cf0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7d00: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
7d10: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
7d20: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
7d30: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7d40: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7d50: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7d60: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7d70: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7d80: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7d90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7da0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
7db0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7dc0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
7dd0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
7de0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
7df0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7e00: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
7e10: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
7e20: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7e30: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
7e40: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7e50: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7e60: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7e70: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7e80: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7e90: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7ea0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
7eb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7ec0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
7ed0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7ee0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
7ef0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7f00: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7f10: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
7f20: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
7f30: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
7f40: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7f50: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7f60: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7f70: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7f80: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7f90: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7fa0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
7fb0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
7fc0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
7fd0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
7fe0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
7ff0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
8000: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
8010: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
8020: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
8030: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
8040: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
8050: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
8060: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
8070: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
8080: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
8090: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
80a0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
80b0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
80c0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
80d0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
80e0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
80f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
8100: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
8110: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
8120: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
8130: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
8140: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
8150: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
8160: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
8170: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
8180: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
8190: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
81a0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
81b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
81c0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
81d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
81e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
81f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8200: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
8210: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8220: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
8230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8240: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8260: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8270: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
8280: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
8290: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
82a0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
82b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
82c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
82d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
82e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
82f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8300: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
8310: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
8320: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
8330: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
8340: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
8350: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
8360: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
8370: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
8380: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
8390: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
83a0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
83b0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
83c0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
83d0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
83e0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
83f0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
8400: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
8410: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
8420: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
8430: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
8440: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
8450: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8460: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
8470: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
8480: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
8490: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
84a0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
84b0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
84c0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
84d0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
84e0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
84f0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
8500: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
8510: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
8520: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
8530: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
8540: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
8550: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
8560: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
8570: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
8580: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
8590: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
85a0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
85b0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
85c0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
85d0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
85e0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
85f0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
8600: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
8610: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
8620: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
8630: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
8640: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
8650: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
8660: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
8670: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8680: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
8690: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
86a0: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
86b0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
86c0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
86d0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
86e0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
86f0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
8700: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
8710: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
8720: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
8730: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
8740: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
8750: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
8760: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8770: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8780: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8790: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
87a0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
87b0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
87c0: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
87d0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
87e0: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
87f0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
8800: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
8810: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
8820: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
8830: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
8840: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
8850: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
8860: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
8870: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8880: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8890: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
88a0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
88b0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
88c0: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
88d0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
88e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
88f0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
8900: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8910: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
8920: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8930: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
8940: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8950: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
8960: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8970: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8980: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8990: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
89c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
89d0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
89e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
89f0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
8a00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8a10: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8a20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8a30: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8a40: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  AL].** <li> [SQL
8a50: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
8a60: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d  TABLE_WHEN_OPEN]
8a70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8a80: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
8a90: 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c  _OVERWRITE].** <
8aa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8ab0: 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20  P_IMMUTABLE].** 
8ac0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8ad0: 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d  AP_BATCH_ATOMIC]
8ae0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8b00: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8b10: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8b20: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8b30: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8b40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8b50: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8b60: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8b70: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8b80: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8b90: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8ba0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8bb0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8bc0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8bd0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8be0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8c00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8c10: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8c20: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8c30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8c40: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8c50: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8c60: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8c70: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8c80: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8c90: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8ca0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8cc0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8cd0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8ce0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8cf0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8d00: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8d10: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8d20: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8d30: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8d40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8d50: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8d60: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8d70: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8d80: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8d90: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8da0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8db0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8dc0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8dd0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8de0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8df0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8e00: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8e10: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8e20: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8e30: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8e40: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8e50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8e60: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8e70: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8e80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e90: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8ea0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8eb0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8ec0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8ed0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8ee0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8ef0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f00: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8f10: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8f20: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8f30: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8f40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8f50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8f60: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8f70: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8f80: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8f90: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8fa0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8fb0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8fc0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8fd0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8fe0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8ff0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
9000: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
9010: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
9020: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9030: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
9040: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
9050: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
9060: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
9070: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
9080: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
9090: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
90a0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
90b0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
90c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
90e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
90f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
9100: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9110: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9120: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
9130: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
9140: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
9150: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
9160: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
9170: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
9180: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
9190: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
91a0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
91b0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
91c0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
91d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
91e0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
91f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9200: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
9210: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9220: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9230: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
9240: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
9250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
9260: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
9270: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
9280: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
9290: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
92a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
92b0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
92c0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
92d0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
92e0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
92f0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
9300: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
9310: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
9320: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
9330: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
9340: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
9350: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
9360: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
9370: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
9380: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
9390: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
93a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
93b0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
93c0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
93d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
93e0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
93f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
9400: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
9410: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
9420: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
9430: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
9440: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
9450: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
9460: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
9470: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9480: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
9490: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
94a0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
94b0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
94c0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
94d0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
94e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
94f0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
9500: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
9510: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
9520: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
9530: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
9540: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
9550: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
9560: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
9570: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
9580: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
9590: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
95a0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
95b0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
95c0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
95d0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
95e0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
95f0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
9600: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
9610: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
9620: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
9630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9640: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9650: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9660: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9670: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9680: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9690: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
96a0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
96b0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
96c0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
96d0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
96e0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
96f0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
9700: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
9710: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
9720: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
9730: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
9740: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9750: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9760: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9770: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9780: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9790: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
97a0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
97b0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
97c0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
97d0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
97e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
97f0: 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a  _SIZE_LIMIT]].**
9800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9810: 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 6f  TL_SIZE_LIMIT] o
9820: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
9830: 20 69 6e 2d 6d 65 6d 6f 72 79 20 56 46 53 20 74   in-memory VFS t
9840: 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
9850: 73 20 5b 73 71 6c 69 74 65 33 5f 64 65 73 65 72  s [sqlite3_deser
9860: 69 61 6c 69 7a 65 28 29 5d 20 74 6f 20 73 65 74  ialize()] to set
9870: 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
9880: 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f  on the size.** o
9890: 66 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  f the in-memory 
98a0: 64 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 61  database.  The a
98b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
98c0: 6e 74 65 72 20 74 6f 20 61 20 5b 73 71 6c 69 74  nter to a [sqlit
98d0: 65 33 5f 69 6e 74 36 34 5d 2e 0a 2a 2a 20 49 66  e3_int64]..** If
98e0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 70 6f 69   the integer poi
98f0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
9900: 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
9910: 66 69 6c 6c 65 64 20 69 6e 20 77 69 74 68 20 74  filled in with t
9920: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6c 69  he.** current li
9930: 6d 69 74 2e 20 20 4f 74 68 65 72 77 69 73 65 20  mit.  Otherwise 
9940: 74 68 65 20 6c 69 6d 69 74 20 69 73 20 73 65 74  the limit is set
9950: 20 74 6f 20 74 68 65 20 6c 61 72 67 65 72 20 6f   to the larger o
9960: 66 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  f the value.** o
9970: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 70 6f  f the integer po
9980: 69 6e 74 65 64 20 74 6f 20 61 6e 64 20 74 68 65  inted to and the
9990: 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
99a0: 65 20 73 69 7a 65 2e 20 20 54 68 65 20 69 6e 74  e size.  The int
99b0: 65 67 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  eger.** pointed 
99c0: 74 6f 20 69 73 20 73 65 74 20 74 6f 20 74 68 65  to is set to the
99d0: 20 6e 65 77 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a   new limit..**.*
99e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
99f0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
9a00: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9a10: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9a20: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9a30: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
9a40: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
9a50: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
9a60: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
9a70: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
9a80: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
9a90: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
9aa0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
9ab0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9ad0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
9ae0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
9af0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
9b00: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
9b10: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
9b20: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
9b30: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
9b40: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
9b50: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
9b60: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
9b70: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
9b80: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
9b90: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
9ba0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
9bb0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
9bc0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
9bd0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
9be0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9bf0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
9c00: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9c10: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9c20: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9c30: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9c40: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9c50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9c60: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9c70: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
9c80: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9c90: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9ca0: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9cb0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9cc0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
9cd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  [[SQLITE_FCNTL_J
9ce0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d  OURNAL_POINTER]]
9cf0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9d00: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9d10: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9d20: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9d30: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9d40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9d50: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9d60: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f  ated with the jo
9d70: 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68  urnal file (eith
9d80: 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62  er.** the [rollb
9d90: 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20  ack journal] or 
9da0: 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64  the [write-ahead
9db0: 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72   log]) for a par
9dc0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9dd0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9de0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9df0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9e00: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9e10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e20: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9e30: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9e40: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9e50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9e60: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9e70: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9e80: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9e90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9ea0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9eb0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9ec0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9ed0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9ee0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9ef0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9f00: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9f10: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9f20: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9f30: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9f40: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9f50: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9f60: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9f70: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9f80: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9f90: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9fa0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9fb0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9fc0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9fd0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9fe0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9ff0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
a000: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a010: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
a020: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
a030: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
a040: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
a050: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
a060: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
a070: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
a080: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
a090: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
a0a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
a0b0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
a0c0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
a0d0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
a0e0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
a0f0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
a100: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
a110: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
a120: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
a130: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
a140: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a150: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
a160: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
a170: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
a180: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
a190: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
a1a0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
a1b0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
a1c0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
a1d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
a1e0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
a1f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
a200: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
a210: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
a220: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
a230: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
a240: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
a250: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
a260: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
a270: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
a280: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
a290: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
a2a0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
a2b0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
a2c0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
a2d0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
a2e0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
a2f0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
a300: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
a310: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
a320: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a330: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
a340: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
a350: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
a360: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
a370: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
a380: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
a390: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
a3a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a3b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a3c0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
a3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
a3e0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
a3f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
a400: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
a410: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
a420: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
a430: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
a440: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
a450: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
a460: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
a470: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
a480: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
a490: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
a4a0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
a4b0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
a4c0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
a4d0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
a4e0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
a4f0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
a500: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
a510: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
a520: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
a530: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
a540: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
a550: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
a560: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
a570: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
a580: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
a590: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
a5a0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
a5b0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
a5c0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
a5d0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
a5e0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
a5f0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a600: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
a610: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
a620: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
a630: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
a640: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a650: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
a660: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
a670: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
a680: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
a690: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
a6a0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
a6b0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
a6c0: 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79  is the new retry
a6d0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
a6e0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
a6f0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
a700: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
a710: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
a720: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
a730: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
a740: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
a750: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
a760: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
a770: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
a780: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
a790: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
a7a0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
a7b0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
a7c0: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
a7d0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
a7e0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
a7f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a800: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
a810: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
a820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a830: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
a840: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a850: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a860: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a870: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a880: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a890: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a8a0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a8b0: 61 68 65 61 64 20 6c 6f 67 20 28 5b 57 41 4c 20  ahead log ([WAL 
a8c0: 66 69 6c 65 5d 29 20 61 6e 64 20 73 68 61 72 65  file]) and share
a8d0: 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 69 6c 65  d memory.** file
a8e0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a8f0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a900: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a910: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a920: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a930: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a940: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a950: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a960: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a970: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a980: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a990: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a9a0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a9b0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a9c0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a9d0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a9e0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a9f0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
aa00: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
aa10: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
aa20: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
aa30: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
aa40: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
aa50: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
aa60: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
aa70: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
aa80: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
aa90: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
aaa0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
aab0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
aac0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
aad0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
aae0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
aaf0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
ab00: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
ab10: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
ab20: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
ab30: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
ab40: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
ab50: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
ab60: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
ab70: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
ab80: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
ab90: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
aba0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
abb0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
abc0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
abd0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
abe0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
abf0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ac00: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
ac10: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
ac20: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
ac30: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
ac40: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
ac50: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
ac60: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
ac70: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
ac80: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
ac90: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
aca0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
acb0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
acc0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
acd0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
ace0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
acf0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
ad00: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
ad10: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
ad20: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
ad30: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
ad40: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
ad50: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
ad60: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
ad70: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
ad80: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
ad90: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
ada0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
adb0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
adc0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
add0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
ade0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
adf0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
ae00: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ae10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
ae20: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
ae30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
ae40: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
ae50: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
ae60: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
ae70: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
ae80: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
ae90: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
aea0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
aeb0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
aec0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
aed0: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
aee0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
aef0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
af00: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
af10: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
af20: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
af30: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
af40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
af50: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
af60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af70: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
af80: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
af90: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
afa0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
afb0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
afc0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
afd0: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
afe0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
aff0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
b000: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
b010: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
b020: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
b030: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b040: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
b050: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
b060: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
b070: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
b080: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
b090: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
b0a0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
b0b0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
b0c0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
b0d0: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
b0e0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
b0f0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
b100: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
b110: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
b120: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
b130: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
b140: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
b150: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
b160: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
b170: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
b180: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
b190: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
b1a0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
b1b0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
b1c0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
b1d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
b1e0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
b1f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
b200: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
b210: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
b220: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
b230: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b240: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
b250: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
b260: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
b270: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
b280: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
b290: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
b2a0: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
b2b0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
b2c0: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
b2d0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
b2e0: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
b2f0: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
b300: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
b310: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
b320: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
b330: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
b340: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
b350: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
b360: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
b370: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
b380: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
b390: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
b3a0: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
b3b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b3c0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
b3d0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
b3e0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
b3f0: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
b400: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b410: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
b420: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
b430: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
b440: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b450: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
b460: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
b470: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
b480: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
b490: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
b4a0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
b4b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b4c0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b4d0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
b4e0: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
b4f0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
b500: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
b510: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
b520: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
b530: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
b540: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
b550: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
b560: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
b570: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
b580: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
b590: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
b5a0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
b5b0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
b5c0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
b5d0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
b5e0: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
b5f0: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
b600: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
b610: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
b620: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
b630: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
b640: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
b650: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
b660: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
b670: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
b680: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
b690: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
b6a0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
b6b0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
b6c0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
b6d0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
b6e0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b6f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b700: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
b710: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
b720: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
b730: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
b740: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
b750: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b760: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
b770: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
b780: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
b790: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
b7a0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
b7b0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
b7c0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
b7d0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
b7e0: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
b7f0: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
b800: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
b810: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
b820: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
b830: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
b840: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
b850: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
b860: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b870: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b880: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b890: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b8a0: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b8b0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b8c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b8d0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b8e0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b8f0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b900: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b910: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b920: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b930: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b940: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b950: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b960: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b980: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b990: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b9a0: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b9b0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b9c0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b9d0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b9e0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b9f0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
ba00: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
ba10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba20: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
ba30: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ba40: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ba50: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
ba60: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
ba70: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
ba80: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ba90: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
baa0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
bab0: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
bac0: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
bad0: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
bae0: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
baf0: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
bb00: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
bb10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bb20: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
bb30: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
bb40: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
bb50: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
bb60: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
bb70: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
bb80: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
bb90: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
bba0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
bbb0: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
bbc0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
bbd0: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
bbe0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
bbf0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
bc00: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
bc10: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
bc20: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
bc30: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
bc40: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
bc50: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
bc60: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
bc70: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
bc80: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
bc90: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
bca0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
bcb0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
bcc0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
bcd0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bce0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
bcf0: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
bd00: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
bd10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
bd20: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
bd30: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
bd40: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
bd50: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
bd60: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
bd70: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
bd80: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
bd90: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
bda0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
bdb0: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
bdc0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
bdd0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
bde0: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
bdf0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
be00: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
be10: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
be20: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
be30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
be40: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
be50: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
be60: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
be70: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
be80: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
be90: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
bea0: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
beb0: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
bee0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bef0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
bf00: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
bf10: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
bf20: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
bf30: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
bf40: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
bf50: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
bf60: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
bf70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
bf80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
bf90: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
bfa0: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
bfb0: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
bfc0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
bfd0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
bfe0: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
bff0: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
c000: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
c010: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
c020: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
c030: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
c040: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
c050: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
c060: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
c070: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
c080: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
c090: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
c0a0: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
c0b0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
c0c0: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
c0d0: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
c0e0: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
c0f0: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
c100: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
c110: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
c120: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
c130: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
c140: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
c150: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
c160: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
c170: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
c180: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
c190: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
c1a0: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
c1b0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
c1c0: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
c1d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
c1e0: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
c1f0: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
c200: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
c210: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
c220: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
c230: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
c240: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
c250: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
c260: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
c270: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
c280: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
c290: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
c2a0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
c2b0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
c2c0: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
c2d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c2e0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
c2f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c300: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
c310: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
c320: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
c330: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
c340: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
c350: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
c360: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
c370: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
c380: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
c390: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
c3a0: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
c3b0: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
c3c0: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
c3d0: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
c3e0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
c3f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c400: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c410: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
c420: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c430: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
c440: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
c450: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
c460: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
c470: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
c480: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
c490: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
c4a0: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
c4b0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
c4c0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
c4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
c4e0: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
c4f0: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
c500: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
c510: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
c520: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c530: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c540: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
c550: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c560: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
c570: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
c580: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
c590: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
c5a0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
c5b0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
c5c0: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
c5d0: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
c5e0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
c5f0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
c600: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
c610: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
c620: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
c630: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
c640: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
c650: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
c660: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
c670: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c680: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
c690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c6a0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
c6b0: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
c6c0: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
c6d0: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
c6e0: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
c6f0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
c700: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
c710: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
c720: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
c730: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
c740: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
c750: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
c760: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
c770: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
c780: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
c790: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
c7a0: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
c7b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
c7c0: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
c7d0: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
c7e0: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
c7f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c800: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
c810: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
c820: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
c830: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c840: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
c850: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
c860: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c870: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c880: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c890: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8a0: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c8b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c8c0: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c8d0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c8e0: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c8f0: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c900: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c910: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c920: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c930: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c940: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c950: 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  e.  .**.** <li>[
c960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c970: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c980: 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  ]].** If the [SQ
c990: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c9a0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
c9b0: 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51  pcode returns SQ
c9c0: 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a  LITE_OK, then.**
c9d0: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
c9e0: 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69  ptor is placed i
c9f0: 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d  n "batch write m
ca00: 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d  ode", which.** m
ca10: 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75  eans all subsequ
ca20: 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74  ent write operat
ca30: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66  ions will be def
ca40: 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a  erred and done.*
ca50: 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20  * atomically at 
ca60: 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45  the next [SQLITE
ca70: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
ca80: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79  OMIC_WRITE].  Sy
ca90: 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f  stems.** that do
caa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74   not support bat
cab0: 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73  ch atomic writes
cac0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
cad0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a  ITE_NOTFOUND..**
cae0: 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75   ^Following a su
caf0: 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f  ccessful SQLITE_
cb00: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cb10: 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69  IC_WRITE and pri
cb20: 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f  or to.** the clo
cb30: 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e  sing [SQLITE_FCN
cb40: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
cb50: 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53  _WRITE] or.** [S
cb60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cb70: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
cb80: 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  E], SQLite will 
cb90: 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69  make.** no VFS i
cba0: 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f  nterface calls o
cbb0: 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69  n the same [sqli
cbc0: 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64  te3_file] file d
cbd0: 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63  escriptor.** exc
cbe0: 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f  ept for calls to
cbf0: 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68   the xWrite meth
cc00: 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65  od and the xFile
cc10: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
cc20: 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46  * with [SQLITE_F
cc30: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e  CNTL_SIZE_HINT].
cc40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
cc50: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
cc60: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a  _ATOMIC_WRITE]].
cc70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
cc80: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
cc90: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cca0: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
ccb0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
ccc0: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
ccd0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cce0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
ccf0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd00: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
cd10: 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d  e performed atom
cd20: 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20  ically..** This 
cd30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
cd40: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
cd50: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
cd60: 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a  the writes were.
cd70: 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64  ** all performed
cd80: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e   successfully an
cd90: 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d  d have been comm
cda0: 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74  itted to persist
cdb0: 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20  ent storage..** 
cdc0: 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
cdd0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
cde0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20   is successful, 
cdf0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
ce00: 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66  l takes.** the f
ce10: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
ce20: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
ce30: 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61  e mode so that a
ce40: 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  ll subsequent.**
ce50: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
ce60: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
ce70: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
ce80: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
ce90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cea0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
ceb0: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cec0: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
ced0: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cee0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
cef0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  C_WRITE]..**.** 
cf00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
cf10: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cf20: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68  IC_WRITE]].** Th
cf30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cf40: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
cf50: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61  WRITE] opcode ca
cf60: 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a  uses all write.*
cf70: 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e  * operations sin
cf80: 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  ce the previous 
cf90: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
cfa0: 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  to .** [SQLITE_F
cfb0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
cfc0: 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72  C_WRITE] to be r
cfd0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e  olled back..** ^
cfe0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
cff0: 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65  l takes the file
d000: 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20   descriptor out 
d010: 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d  of batch write m
d020: 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61  ode.** so that a
d030: 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72  ll subsequent wr
d040: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
d050: 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a  re independent..
d060: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d070: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c  never invoke SQL
d080: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
d090: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  CK_ATOMIC_WRITE 
d0a0: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
d0b0: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
d0c0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
d0d0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
d0e0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
d0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d100: 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 5d  L_LOCK_TIMEOUT]]
d110: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d120: 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f  FCNTL_LOCK_TIMEO
d130: 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65  UT] opcode cause
d140: 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f 62  s attempts to ob
d150: 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20 6c  tain.** a file l
d160: 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78 4c  ock using the xL
d170: 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b 20  ock or xShmLock 
d180: 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 56  methods of the V
d190: 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66 6f  FS to wait.** fo
d1a0: 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69 73  r up to M millis
d1b0: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66 61  econds before fa
d1c0: 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20 69  iling, where M i
d1d0: 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a 2a  s the single .**
d1e0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
d1f0: 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  r parameter..**.
d200: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d210: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
d220: 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ON]].** The [SQL
d230: 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
d240: 45 52 53 49 4f 4e 5d 20 6f 70 63 6f 64 65 20 69  ERSION] opcode i
d250: 73 20 75 73 65 64 20 74 6f 20 64 65 74 65 63 74  s used to detect
d260: 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61   changes to.** a
d270: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
d280: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
d290: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
d2a0: 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
d2b0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 65 20  integer..** The 
d2c0: 22 64 61 74 61 20 76 65 72 73 69 6f 6e 22 20 66  "data version" f
d2d0: 6f 72 20 74 68 65 20 70 61 67 65 72 20 69 73 20  or the pager is 
d2e0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
d2f0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 0a 2a   pointer.  The.*
d300: 2a 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e 22  * "data version"
d310: 20 63 68 61 6e 67 65 73 20 77 68 65 6e 65 76 65   changes wheneve
d320: 72 20 61 6e 79 20 63 68 61 6e 67 65 20 6f 63 63  r any change occ
d330: 75 72 73 20 74 6f 20 74 68 65 20 63 6f 72 72 65  urs to the corre
d340: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64 61 74 61  sponding.** data
d350: 62 61 73 65 20 66 69 6c 65 2c 20 65 69 74 68 65  base file, eithe
d360: 72 20 74 68 72 6f 75 67 68 20 53 51 4c 20 73 74  r through SQL st
d370: 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20  atements on the 
d380: 73 61 6d 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  same database.**
d390: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 72 20 74   connection or t
d3a0: 68 72 6f 75 67 68 20 74 72 61 6e 73 61 63 74 69  hrough transacti
d3b0: 6f 6e 73 20 63 6f 6d 6d 69 74 74 65 64 20 62 79  ons committed by
d3c0: 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
d3d0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
d3e0: 73 20 70 6f 73 73 69 62 6c 79 20 69 6e 20 6f 74  s possibly in ot
d3f0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 2e 20 54  her processes. T
d400: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
d410: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20  l_changes()].** 
d420: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
d430: 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 69 66   used to find if
d440: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 6f 6e   any database on
d450: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
d460: 68 61 73 20 63 68 61 6e 67 65 64 2c 0a 2a 2a 20  has changed,.** 
d470: 62 75 74 20 74 68 61 74 20 69 6e 74 65 72 66 61  but that interfa
d480: 63 65 20 72 65 73 70 6f 6e 64 73 20 74 6f 20 63  ce responds to c
d490: 68 61 6e 67 65 73 20 6f 6e 20 54 45 4d 50 20 61  hanges on TEMP a
d4a0: 73 20 77 65 6c 6c 20 61 73 20 4d 41 49 4e 20 61  s well as MAIN a
d4b0: 6e 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70  nd does.** not p
d4c0: 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69  rovide a mechani
d4d0: 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61  sm to detect cha
d4e0: 6e 67 65 73 20 74 6f 20 4d 41 49 4e 20 6f 6e 6c  nges to MAIN onl
d4f0: 79 2e 20 20 41 6c 73 6f 2c 20 74 68 65 0a 2a 2a  y.  Also, the.**
d500: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
d510: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
d520: 66 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74 6f  face responds to
d530: 20 69 6e 74 65 72 6e 61 6c 20 63 68 61 6e 67 65   internal change
d540: 73 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a 20 6f 6d  s only and.** om
d550: 69 74 73 20 63 68 61 6e 67 65 73 20 6d 61 64 65  its changes made
d560: 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61   by other databa
d570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 20  se connections. 
d580: 20 54 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   The.** [PRAGMA 
d590: 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f  data_version] co
d5a0: 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65 20 61 20  mmand provide a 
d5b0: 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74  mechanism to det
d5c0: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
d5d0: 2a 20 61 20 73 69 6e 67 6c 65 20 61 74 74 61 63  * a single attac
d5e0: 68 65 64 20 64 61 74 61 62 61 73 65 20 74 68 61  hed database tha
d5f0: 74 20 6f 63 63 75 72 20 64 75 65 20 74 6f 20 6f  t occur due to o
d600: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
d610: 6e 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75  nnections,.** bu
d620: 74 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 20  t omits changes 
d630: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
d640: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
d650: 65 63 74 69 6f 6e 20 6f 6e 20 77 68 69 63 68 20  ection on which 
d660: 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  it is.** called.
d670: 20 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74    This file cont
d680: 72 6f 6c 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  rol is the only 
d690: 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74  mechanism to det
d6a0: 65 63 74 20 63 68 61 6e 67 65 73 20 74 68 61 74  ect changes that
d6b0: 0a 2a 2a 20 68 61 70 70 65 6e 20 65 69 74 68 65  .** happen eithe
d6c0: 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
d6d0: 65 78 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 74  externally and t
d6e0: 68 61 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  hat are associat
d6f0: 65 64 20 77 69 74 68 0a 2a 2a 20 61 20 70 61 72  ed with.** a par
d700: 74 69 63 75 6c 61 72 20 61 74 74 61 63 68 65 64  ticular attached
d710: 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 3c 2f   database..** </
d720: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
d730: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
d740: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
d750: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
d770: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d780: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
d790: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
d7a0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
d7b0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
d7c0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d7d0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d7e0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
d7f0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
d800: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
d810: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d820: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
d830: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
d840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d850: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
d860: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
d870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d880: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
d890: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
d8a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d8b0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
d8c0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
d8d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d8e0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
d8f0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
d900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d910: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
d920: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
d930: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d940: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
d950: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
d960: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d970: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
d980: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
d990: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d9a0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
d9b0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
d9c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
d9d0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
d9e0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
d9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
da00: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
da10: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
da20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
da30: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
da40: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
da50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
da60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
da70: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
da80: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
da90: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
daa0: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
dab0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
dac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dad0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
dae0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
daf0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
db00: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
db10: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
db20: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
db30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db40: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
db50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
db60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
db70: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
db80: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
db90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dba0: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20  NTL_RBU         
dbb0: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64             26.#d
dbc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dbd0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20  TL_VFS_POINTER  
dbe0: 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65            27.#de
dbf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dc00: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
dc10: 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66  R        28.#def
dc20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dc30: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
dc40: 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69  E       29.#defi
dc50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dc60: 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20  PDB             
dc70: 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e         30.#defin
dc80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
dc90: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
dca0: 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65  E     31.#define
dcb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
dcc0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
dcd0: 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
dce0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
dcf0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
dd00: 54 45 20 20 33 33 0a 23 64 65 66 69 6e 65 20 53  TE  33.#define S
dd10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
dd20: 5f 54 49 4d 45 4f 55 54 20 20 20 20 20 20 20 20  _TIMEOUT        
dd30: 20 20 20 33 34 0a 23 64 65 66 69 6e 65 20 53 51     34.#define SQ
dd40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
dd50: 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20  VERSION         
dd60: 20 20 33 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    35.#define SQL
dd70: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c  ITE_FCNTL_SIZE_L
dd80: 49 4d 49 54 20 20 20 20 20 20 20 20 20 20 20 20  IMIT            
dd90: 20 33 36 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   36../* deprecat
dda0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
ddb0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
ddc0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ddd0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
dde0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ddf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
de00: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
de10: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
de20: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
de30: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
de40: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
de50: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
de60: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
de70: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
de80: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
de90: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
dea0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
deb0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
dec0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
ded0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
dee0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
def0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
df00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
df10: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
df20: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
df30: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
df40: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
df50: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
df60: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
df70: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
df80: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
df90: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
dfa0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
dfb0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
dfc0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
dfd0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
dfe0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
dff0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
e000: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
e010: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
e020: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
e030: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
e040: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
e050: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
e060: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
e070: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
e080: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
e090: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
e0a0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
e0b0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
e0c0: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
e0d0: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
e0e0: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
e0f0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
e100: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
e110: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
e120: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
e130: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
e140: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
e150: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e160: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
e170: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
e180: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e190: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e1a0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
e1b0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
e1c0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
e1d0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
e1e0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
e1f0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
e200: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
e210: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
e220: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
e230: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e240: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
e250: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
e260: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
e270: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
e280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20  ..**.** The VFS 
e290: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 6f 6d  interface is som
e2a0: 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65 64 20  etimes extended 
e2b0: 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20 6d 65  by adding new me
e2c0: 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68  thods onto.** th
e2d0: 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74 69 6d  e end.  Each tim
e2e0: 65 20 73 75 63 68 20 61 6e 20 65 78 74 65 6e 73  e such an extens
e2f0: 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20  ion occurs, the 
e300: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a  iVersion field.*
e310: 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64  * is incremented
e320: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  .  The iVersion 
e330: 76 61 6c 75 65 20 73 74 61 72 74 65 64 20 6f 75  value started ou
e340: 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c  t as 1 in.** SQL
e350: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35  ite [version 3.5
e360: 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .0] on [dateof:3
e370: 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72  .5.0], then incr
e380: 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69  eased to 2.** wi
e390: 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  th SQLite [versi
e3a0: 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.7.0] on [da
e3b0: 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64  teof:3.7.0], and
e3c0: 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 0a   then increased.
e3d0: 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53 51 4c  ** to 3 with SQL
e3e0: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37  ite [version 3.7
e3f0: 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .6] on [dateof:3
e400: 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e  .7.6].  Addition
e410: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79  al fields.** may
e420: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
e430: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
e440: 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65 20 69  object and the i
e450: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a  Version value.**
e460: 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20 61 67   may increase ag
e470: 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20 76 65  ain in future ve
e480: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
e490: 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  ..** Note that t
e4a0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
e4b0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e4c0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
e4d0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 69 74  s in the transit
e4e0: 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69  ion from.** SQLi
e4f0: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e  te [version 3.5.
e500: 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33  9] to [version 3
e510: 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .6.0] on [dateof
e520: 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79  :3.6.0].** and y
e530: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
e540: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f  field was not mo
e550: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
e560: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
e570: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
e580: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
e590: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
e5a0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
e5b0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
e5c0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
e5d0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
e5e0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
e5f0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
e600: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
e610: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
e620: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
e630: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
e640: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
e650: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
e660: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
e670: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
e680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
e690: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
e6a0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
e6b0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
e6c0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
e6d0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
e6e0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
e6f0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
e700: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
e710: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
e720: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
e730: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
e740: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
e750: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
e760: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
e770: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
e780: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
e790: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
e7a0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
e7b0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
e7c0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
e7d0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
e7e0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
e7f0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
e800: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
e810: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
e820: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
e830: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
e840: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
e850: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
e860: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
e870: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
e880: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
e890: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
e8a0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
e8b0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
e8c0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
e8d0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
e8e0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
e8f0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
e900: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
e910: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
e920: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
e930: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
e940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e950: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
e960: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
e970: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
e980: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
e990: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
e9a0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
e9b0: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
e9c0: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
e9d0: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
e9e0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
e9f0: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
ea00: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
ea10: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
ea20: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
ea30: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
ea40: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
ea50: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
ea60: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
ea70: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
ea80: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
ea90: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
eaa0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
eab0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
eac0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
ead0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
eae0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
eaf0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
eb00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
eb10: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
eb20: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
eb30: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
eb40: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
eb50: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
eb60: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
eb70: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
eb80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
eb90: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
eba0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
ebb0: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
ebc0: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
ebd0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
ebe0: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
ebf0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
ec00: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
ec10: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
ec20: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
ec30: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
ec40: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
ec50: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
ec60: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
ec70: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
ec80: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
ec90: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
eca0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
ecb0: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
ecc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
ecd0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
ece0: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
ecf0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
ed00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
ed10: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
ed20: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
ed30: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
ed40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
ed50: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
ed60: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
ed70: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
ed80: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
ed90: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
eda0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
edb0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
edc0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
edd0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
ede0: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
edf0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
ee00: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
ee10: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
ee20: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
ee30: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
ee40: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
ee50: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
ee60: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
ee70: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
ee80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ee90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
eea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
eeb0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
eec0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
eed0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
eee0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
eef0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
ef00: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ef10: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
ef20: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ef30: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
ef40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ef50: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
ef60: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ef70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
ef80: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
ef90: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
efa0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
efb0: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
efc0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
efd0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
efe0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
eff0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
f000: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
f010: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
f020: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
f030: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
f040: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
f050: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
f060: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
f070: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
f080: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
f090: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
f0a0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
f0b0: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
f0c0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
f0d0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
f0e0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
f0f0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
f100: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
f110: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
f120: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
f130: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
f140: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
f150: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
f160: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
f170: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
f180: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
f190: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
f1a0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
f1b0: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
f1c0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
f1d0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
f1e0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
f1f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
f200: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
f210: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
f220: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
f230: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
f240: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
f250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
f260: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
f270: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
f280: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
f290: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
f2a0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
f2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
f2c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
f2d0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
f2e0: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
f2f0: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
f300: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
f310: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
f320: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
f330: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
f340: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
f350: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
f360: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
f370: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
f380: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
f390: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
f3a0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
f3b0: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
f3c0: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
f3d0: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
f3e0: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
f3f0: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
f400: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f410: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
f420: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
f430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
f440: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
f450: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
f460: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
f470: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
f480: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
f490: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
f4a0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
f4b0: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
f4c0: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
f4d0: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
f4e0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
f4f0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
f500: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
f510: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
f520: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
f530: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
f540: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
f550: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
f560: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
f570: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
f580: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
f590: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
f5a0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
f5b0: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
f5c0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
f5d0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
f5e0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
f5f0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
f600: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
f610: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
f620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
f630: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
f640: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
f650: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f660: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
f670: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
f680: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
f690: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
f6a0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
f6b0: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
f6c0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
f6d0: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
f6e0: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
f6f0: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
f700: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
f710: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
f720: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
f730: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
f740: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
f750: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
f760: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
f770: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
f780: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
f790: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
f7a0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
f7b0: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
f7c0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
f7d0: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
f7e0: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
f7f0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
f800: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
f810: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
f820: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
f830: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
f840: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
f850: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
f860: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f870: 44 0a 2a 2a 20 66 6c 61 67 20 69 73 20 6e 65 76  D.** flag is nev
f880: 65 72 20 61 63 74 75 61 6c 6c 79 20 75 73 65 64  er actually used
f890: 20 61 6e 64 20 69 73 20 6e 6f 74 20 69 6d 70 6c   and is not impl
f8a0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 68 65 20 62  emented in the b
f8b0: 75 69 6c 74 2d 69 6e 0a 2a 2a 20 56 46 53 65 73  uilt-in.** VFSes
f8c0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 54 68 65   of SQLite.  The
f8d0: 20 66 69 6c 65 20 69 73 20 6e 61 6d 65 64 20 62   file is named b
f8e0: 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
f8f0: 75 6d 65 6e 74 20 61 6e 64 20 63 61 6e 20 62 65  ument and can be
f900: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
f910: 20 54 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   The xAccess met
f920: 68 6f 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  hod returns [SQL
f930: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f940: 73 73 20 6f 72 20 73 6f 6d 65 0a 2a 2a 20 6e 6f  ss or some.** no
f950: 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64  n-zero error cod
f960: 65 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  e if there is an
f970: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 72 20 69 66   I/O error or if
f980: 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
f990: 74 68 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  the file given i
f9a0: 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  n the second arg
f9b0: 75 6d 65 6e 74 20 69 73 20 69 6c 6c 65 67 61 6c  ument is illegal
f9c0: 2e 20 20 49 66 20 53 51 4c 49 54 45 5f 4f 4b 0a  .  If SQLITE_OK.
f9d0: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20  ** is returned, 
f9e0: 74 68 65 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  then non-zero or
f9f0: 20 7a 65 72 6f 20 69 73 20 77 72 69 74 74 65 6e   zero is written
fa00: 20 69 6e 74 6f 20 2a 70 52 65 73 4f 75 74 20 74   into *pResOut t
fa10: 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 77 68  o indicate.** wh
fa20: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
fa30: 20 66 69 6c 65 20 69 73 20 61 63 63 65 73 73 69   file is accessi
fa40: 62 6c 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 53 51  ble.  .**.** ^SQ
fa50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
fa60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
fa70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
fa80: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
fa90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
faa0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
fab0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
fac0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
fad0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
fae0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
faf0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
fb00: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
fb10: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
fb20: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
fb30: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
fb40: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
fb50: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
fb60: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
fb70: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
fb80: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
fb90: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
fba0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
fbb0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
fbc0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
fbd0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
fbe0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
fbf0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
fc00: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
fc10: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
fc20: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
fc30: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fc40: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
fc50: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
fc60: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
fc70: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
fc80: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
fc90: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
fca0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
fcb0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
fcc0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
fcd0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
fce0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
fcf0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
fd00: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
fd10: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
fd20: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
fd30: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
fd40: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
fd50: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
fd60: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
fd70: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
fd80: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
fd90: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
fda0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
fdb0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
fdc0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
fdd0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
fde0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
fdf0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
fe00: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
fe10: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
fe20: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
fe30: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
fe40: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
fe50: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
fe60: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
fe70: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
fe80: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
fe90: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
fea0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
feb0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
fec0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
fed0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
fee0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
fef0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
ff00: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
ff10: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
ff20: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
ff30: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
ff40: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
ff50: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
ff60: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
ff70: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
ff80: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
ff90: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
ffa0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
ffb0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
ffc0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
ffd0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
ffe0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
fff0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
10000 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
10010 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
10020 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
10030 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
10040 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
10050 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
10060 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
10070 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
10080 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
10090 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
100a0 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
100b0 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
100c0 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
100d0 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
100e0 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
100f0 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
10100 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
10110 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
10120 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
10130 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
10140 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
10150 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
10160 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
10170 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
10180 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
10190 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
101a0 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
101b0 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
101c0 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
101d0 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
101e0 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
101f0 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
10200 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
10210 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
10220 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
10230 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
10240 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
10250 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
10260 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
10270 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
10280 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
10290 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
102a0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
102b0 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
102c0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
102d0 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
102e0 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
102f0 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
10300 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
10310 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
10320 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
10330 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
10340 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
10350 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
10360 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
10370 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
10380 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
10390 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
103a0 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
103b0 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
103c0 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
103d0 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
103e0 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
103f0 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
10400 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
10410 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
10420 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
10430 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
10440 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
10450 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
10460 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
10470 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
10480 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
10490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
104a0 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
104b0 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
104c0 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
104d0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
104e0 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
104f0 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
10500 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
10510 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
10520 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
10530 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10540 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
10550 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
10560 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
10570 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
10580 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
10590 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
105a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
105b0 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
105c0 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
105d0 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
105e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
105f0 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
10600 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
10610 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
10620 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
10630 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10640 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
10650 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
10660 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
10670 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10680 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
10690 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
106a0 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
106b0 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
106c0 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
106d0 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
106e0 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
106f0 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
10700 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
10710 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
10720 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
10730 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
10740 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
10750 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
10760 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
10770 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
10780 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
10790 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
107a0 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
107b0 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
107c0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
107d0 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
107e0 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
107f0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10800 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
10810 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
10820 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
10830 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
10840 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10850 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
10860 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
10870 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
10880 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
10890 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
108a0 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
108b0 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
108c0 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
108d0 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
108e0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
108f0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
10900 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
10910 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10920 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
10930 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
10940 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
10950 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
10960 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
10970 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10980 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10990 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
109a0 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
109b0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
109c0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
109d0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
109e0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
109f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
10a00 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
10a10 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10a20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10a30 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
10a40 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
10a50 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
10a60 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
10a70 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
10a80 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
10a90 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
10aa0 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
10ab0 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
10ac0 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
10ad0 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
10ae0 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
10af0 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
10b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10b10 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10b20 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
10b30 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10b40 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10b50 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
10b60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
10b70 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
10b80 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
10b90 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
10ba0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
10bb0 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
10bc0 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
10bd0 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
10be0 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
10bf0 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
10c00 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
10c10 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
10c20 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
10c30 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
10c40 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
10c50 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
10c60 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10c70 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
10c80 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10c90 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
10ca0 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
10cb0 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
10cc0 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
10cd0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
10ce0 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
10cf0 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
10d00 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
10d10 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
10d20 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
10d30 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10d40 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
10d50 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
10d60 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
10d70 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10d80 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
10d90 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
10da0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
10db0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
10dc0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
10dd0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10de0 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
10df0 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10e00 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
10e10 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
10e20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10e30 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
10e40 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
10e50 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
10e60 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
10e70 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
10e80 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
10e90 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
10ea0 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10eb0 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
10ec0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10ed0 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
10ee0 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
10ef0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10f00 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
10f10 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10f20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
10f30 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
10f40 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
10f50 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
10f60 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
10f70 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
10f80 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
10f90 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
10fa0 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
10fb0 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
10fc0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10fd0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
10fe0 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
10ff0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
11000 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
11010 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
11020 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
11030 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
11040 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
11050 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
11060 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
11070 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
11080 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
11090 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
110a0 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
110b0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
110c0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
110d0 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
110e0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
110f0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
11100 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
11110 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
11120 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
11130 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
11140 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
11150 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
11160 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
11170 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
11180 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
11190 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
111a0 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
111b0 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
111c0 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
111d0 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
111e0 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
111f0 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
11200 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11210 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
11220 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
11230 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
11240 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
11250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11260 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
11270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11280 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
11290 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
112a0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
112b0 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
112c0 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
112d0 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
112e0 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
112f0 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
11300 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
11310 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
11320 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
11330 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
11340 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
11350 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
11360 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
11370 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
11380 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
11390 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
113a0 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
113b0 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
113c0 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
113d0 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
113e0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
113f0 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
11400 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
11420 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
11430 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
11440 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
11450 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
11460 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
11470 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
11480 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
11490 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
114a0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
114b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
114c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
114d0 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
114e0 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
114f0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11500 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
11510 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
11520 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
11530 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
11540 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
11550 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
11560 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
11570 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
11580 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
11590 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
115a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
115b0 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
115c0 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
115d0 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
115e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
115f0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
11600 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
11610 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
11620 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
11630 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
11640 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11650 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
11660 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
11670 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11680 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
11690 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
116a0 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
116b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
116c0 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
116d0 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
116e0 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
116f0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
11700 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
11710 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11720 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
11730 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
11740 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
11750 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
11760 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11770 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
11780 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11790 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
117a0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
117b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
117c0 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
117d0 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
117e0 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
117f0 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
11800 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11810 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
11820 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
11830 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11840 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
11850 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
11860 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
11870 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
11880 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
11890 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
118a0 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
118b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
118c0 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
118d0 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
118e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
118f0 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
11900 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
11910 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
11920 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
11930 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
11940 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
11950 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11960 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
11970 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
11980 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11990 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
119a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
119b0 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
119c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
119d0 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
119e0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
119f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
11a00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11a10 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
11a20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
11a30 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
11a40 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
11a50 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
11a60 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
11a70 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
11a80 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
11a90 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
11aa0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11ab0 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
11ac0 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
11ad0 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
11ae0 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
11af0 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
11b00 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
11b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11b20 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11b30 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
11b40 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
11b50 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
11b60 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
11b70 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
11b80 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
11b90 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
11ba0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
11bb0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11bc0 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
11bd0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
11be0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
11bf0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11c00 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
11c10 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
11c20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
11c30 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
11c40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
11c50 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
11c60 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
11c70 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
11c80 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
11c90 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
11ca0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
11cb0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
11cc0 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
11cd0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
11ce0 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
11cf0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
11d00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
11d10 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
11d20 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
11d30 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
11d40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11d50 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
11d60 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
11d70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11d80 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
11d90 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
11da0 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
11db0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
11dc0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
11dd0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11de0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
11df0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
11e00 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11e10 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11e20 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
11e30 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
11e40 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
11e50 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
11e60 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
11e70 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
11e80 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11e90 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
11ea0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11eb0 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
11ec0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
11ed0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
11ee0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
11ef0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
11f00 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11f10 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
11f20 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
11f30 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
11f40 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11f50 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11f60 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
11f70 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
11f80 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
11f90 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
11fa0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
11fb0 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
11fc0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
11fd0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
11fe0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
11ff0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
12000 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
12010 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
12020 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
12030 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
12040 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
12050 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
12060 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
12070 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
12080 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
12090 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
120a0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
120b0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
120c0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
120d0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
120e0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
120f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
12100 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
12110 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12120 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
12130 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
12140 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
12150 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12160 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
12170 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
12180 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
12190 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
121a0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
121b0 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
121c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
121d0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
121e0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
121f0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
12200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
12210 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
12220 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
12230 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
12240 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
12250 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
12260 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
12270 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
12280 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
12290 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
122a0 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
122b0 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
122c0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
122d0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
122e0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
122f0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
12300 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
12310 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
12320 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
12330 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12340 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
12350 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
12360 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
12370 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
12380 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
12390 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
123a0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
123b0 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
123c0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
123d0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
123e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
123f0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
12400 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
12410 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12420 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
12430 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
12440 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
12450 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
12460 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12470 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
12480 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
12490 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
124a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
124b0 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
124c0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
124d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
124e0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
124f0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12500 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
12510 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
12520 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
12530 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
12540 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
12550 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
12560 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
12570 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
12580 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
12590 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
125a0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
125b0 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
125c0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
125d0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
125e0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
125f0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
12600 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
12610 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
12620 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
12630 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12640 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12650 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
12660 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12670 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
12680 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
12690 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
126a0 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
126b0 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
126c0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
126d0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
126e0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
126f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12700 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
12710 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
12720 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
12730 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
12740 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
12750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12760 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
12770 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
12780 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
12790 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
127a0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
127b0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
127c0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
127d0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
127e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
127f0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
12800 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
12810 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
12820 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
12830 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
12840 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
12850 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
12860 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
12870 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12880 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
12890 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
128a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
128b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
128c0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
128d0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
128e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
128f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
12900 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
12910 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
12920 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
12930 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
12940 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
12950 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
12960 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12970 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
12980 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
12990 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
129a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
129b0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
129c0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
129d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
129e0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
129f0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
12a00 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
12a10 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
12a20 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
12a30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12a40 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
12a50 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
12a60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
12a70 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
12a80 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12a90 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
12aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12ab0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
12ac0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
12ad0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
12ae0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
12af0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
12b00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
12b10 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
12b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b30 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
12b40 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
12b50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12b60 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
12b70 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
12b80 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
12b90 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
12ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
12bb0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
12bc0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
12bd0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
12be0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
12bf0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
12c00 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
12c10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
12c20 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
12c30 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
12c40 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
12c50 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
12c60 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
12c70 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
12c80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12c90 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
12ca0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
12cb0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
12cc0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
12cd0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
12ce0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
12cf0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
12d00 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
12d10 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
12d20 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
12d30 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
12d40 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
12d50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
12d60 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
12d70 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
12d80 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
12d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
12da0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
12db0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
12dc0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12dd0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
12de0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
12df0 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
12e00 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
12e10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12e20 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
12e30 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
12e40 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
12e50 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
12e60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
12e70 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
12e80 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12e90 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
12ea0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
12eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12ec0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
12ed0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ee0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
12ef0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
12f00 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
12f10 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
12f20 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
12f30 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12f40 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
12f50 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
12f60 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
12f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12f80 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
12f90 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
12fa0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
12fb0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
12fc0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
12fd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12fe0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
12ff0 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
13000 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
13010 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
13020 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
13030 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
13040 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
13050 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
13060 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
13070 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
13080 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
13090 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
130a0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
130b0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
130c0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
130d0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
130e0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
130f0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
13100 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
13110 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
13120 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
13130 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
13140 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
13150 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
13160 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
13170 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
13180 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
13190 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
131a0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
131b0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
131c0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
131d0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
131e0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
131f0 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
13200 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
13210 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
13220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
13230 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
13240 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
13250 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
13260 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
13270 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
13280 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
13290 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
132a0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
132b0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
132c0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
132d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
132e0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
132f0 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
13300 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
13310 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
13320 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
13330 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
13340 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13350 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
13360 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
13370 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
13380 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
13390 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
133a0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
133b0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
133c0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
133d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
133e0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
133f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
13400 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
13410 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
13420 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
13430 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
13440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
13450 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
13460 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
13470 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
13480 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
13490 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
134a0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
134b0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
134c0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
134d0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
134e0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
134f0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
13500 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
13510 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
13520 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
13530 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
13540 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
13550 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
13560 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13570 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
13580 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
13590 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
135a0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
135b0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
135c0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
135d0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
135e0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
135f0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
13600 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
13610 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
13620 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
13630 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
13640 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
13650 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
13660 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
13670 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
13680 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
13690 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
136a0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
136b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
136c0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
136d0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
136e0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
136f0 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
13700 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
13710 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
13720 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
13730 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
13740 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
13750 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
13760 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
13770 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
13780 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
13790 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
137a0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
137b0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
137c0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
137d0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
137e0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
137f0 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
13800 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
13810 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
13820 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
13830 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
13840 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
13850 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
13860 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
13870 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
13880 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
13890 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
138a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
138b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
138c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
138d0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
138e0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
138f0 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
13900 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
13910 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
13920 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
13930 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
13940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13950 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
13960 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
13970 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
13980 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
13990 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
139a0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
139b0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
139c0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
139d0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
139e0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
139f0 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
13a00 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
13a10 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
13a20 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
13a30 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
13a40 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
13a50 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
13a60 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
13a70 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
13a80 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
13a90 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
13aa0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
13ab0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13ac0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
13ad0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
13ae0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
13af0 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
13b00 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
13b10 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
13b20 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
13b30 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
13b40 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
13b50 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
13b60 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
13b70 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
13b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
13b90 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
13ba0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
13bb0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
13bc0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
13bd0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
13be0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
13bf0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13c00 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
13c10 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13c20 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
13c30 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
13c40 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
13c50 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
13c60 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
13c70 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
13c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
13c90 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
13ca0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
13cb0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
13cc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13cd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13ce0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
13cf0 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
13d00 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
13d10 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
13d20 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
13d30 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
13d40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
13d50 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
13d60 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
13d70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13d80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13d90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
13da0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
13db0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13dc0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13dd0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13de0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13df0 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13e00 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13e10 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13e20 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13e30 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13e40 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
13e50 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
13e60 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
13e70 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
13e80 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
13e90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
13ea0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
13eb0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
13ec0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
13ed0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
13ee0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
13ef0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
13f00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
13f10 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
13f20 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
13f30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13f40 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
13f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13f60 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
13f70 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13f80 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13f90 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13fa0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13fb0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13fc0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
13fd0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
13fe0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
13ff0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
14000 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
14010 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
14020 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
14030 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
14040 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
14050 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
14060 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14070 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14080 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14090 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
140a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
140b0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
140c0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
140d0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
140e0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
140f0 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
14100 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
14110 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
14120 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
14130 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14140 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
14150 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
14160 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14170 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14180 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
14190 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
141a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
141b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
141c0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
141d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
141e0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
141f0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14200 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14210 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14220 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14230 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14240 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
14250 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14260 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14270 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
14280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14290 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
142a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
142b0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
142c0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
142d0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
142e0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
142f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14300 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
14310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14320 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
14330 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
14340 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
14350 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
14360 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
14370 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
14380 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
14390 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
143a0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
143b0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
143c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
143d0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
143e0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
143f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14400 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14410 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14420 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14430 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14440 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14450 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14460 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
14470 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
14480 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14490 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
144a0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
144b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
144c0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
144d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
144e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
144f0 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
14500 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
14510 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14520 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14530 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14540 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
14550 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14560 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14570 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
14580 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
14590 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
145a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
145b0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
145c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
145d0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
145e0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
145f0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
14600 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
14610 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
14620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14630 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14640 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14650 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
14660 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
14670 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
14680 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14690 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
146a0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
146b0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
146c0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
146d0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
146e0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
146f0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
14700 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14710 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
14720 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
14730 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
14740 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
14750 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
14760 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
14770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14780 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
14790 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
147a0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
147b0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
147c0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
147d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
147e0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
147f0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14800 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14810 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
14820 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
14830 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
14840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
14850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14860 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
14870 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14880 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
14890 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
148a0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
148b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
148c0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
148d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
148e0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
148f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14900 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14910 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14920 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
14930 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14940 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14950 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
14960 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14970 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14980 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
14990 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
149a0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
149b0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
149c0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
149d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
149e0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
149f0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
14a00 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14a10 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14a20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
14a30 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
14a40 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
14a50 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
14a60 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
14a70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14a80 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14a90 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
14aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14ab0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
14ac0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14ae0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
14af0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14b00 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
14b10 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14b20 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
14b30 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14b40 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14b50 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14b60 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14b70 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14b80 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14b90 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
14ba0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14bb0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14bc0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14bd0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14be0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
14bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
14c00 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
14c10 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
14c20 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14c30 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
14c40 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14c50 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
14c60 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
14c70 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
14c80 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
14c90 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
14ca0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
14cb0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
14cc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14cd0 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
14ce0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
14cf0 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
14d00 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14d10 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14d20 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
14d30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
14d40 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14d50 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e  .** type int, in
14d60 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
14d70 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66  oolean, which if
14d80 20 74 72 75 65 20 70 72 6f 76 69 64 65 73 20 61   true provides a
14d90 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69   hint to.** SQLi
14da0 74 65 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c  te that it shoul
14db0 64 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65  d avoid large me
14dc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14dd0 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   if possible..**
14de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e   SQLite will run
14df0 20 66 61 73 74 65 72 20 69 66 20 69 74 20 69 73   faster if it is
14e00 20 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61   free to make la
14e10 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14e20 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73  ations,.** but s
14e30 6f 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ome application 
14e40 6d 69 67 68 74 20 70 72 65 66 65 72 20 74 6f 20  might prefer to 
14e50 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78  run slower in ex
14e60 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75  change for.** gu
14e70 61 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d  arantees about m
14e80 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74  emory fragmentat
14e90 69 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73  ion that are pos
14ea0 73 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a  sible if large.*
14eb0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72  * allocations ar
14ec0 65 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73  e avoided.  This
14ed0 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c   hint is normall
14ee0 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  y off..** </dd>.
14ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f00 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14f10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f20 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
14f30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14f50 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
14f60 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14f70 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14f80 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
14f90 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14fa0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
14fb0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
14fc0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
14fd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14fe0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
14ff0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
15000 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
15010 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
15020 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
15030 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
15040 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
15050 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
15060 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
15070 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15080 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
15090 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
150a0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
150b0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
150c0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
150d0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
150e0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
150f0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
15100 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
15110 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
15120 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
15130 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
15140 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
15150 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
15160 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
15170 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
15180 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
15190 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
151a0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
151b0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
151c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
151d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
151e0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
151f0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15200 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
15210 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15220 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69  SCRATCH option i
15230 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  s no longer used
15240 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15250 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15260 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
15270 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15280 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
15290 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
152a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
152b0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
152c0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
152d0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
152e0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
152f0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
15300 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
15310 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
15320 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15330 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
15340 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15350 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
15360 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
15370 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
15380 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15390 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
153a0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
153b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
153c0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
153d0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
153e0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
153f0 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
15400 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
15410 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
15420 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
15430 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
15440 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
15450 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
15460 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
15470 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
15480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
15490 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
154a0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
154b0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
154c0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
154d0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
154e0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
154f0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
15500 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
15510 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
15520 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
15530 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
15540 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
15550 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
15560 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
15570 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
15580 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
15590 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
155a0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
155b0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
155c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
155d0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
155e0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
155f0 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
15600 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
15610 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
15620 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15630 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
15640 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
15650 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
15660 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
15670 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
15680 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
15690 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
156a0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
156b0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
156c0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
156d0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
156e0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
156f0 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
15700 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
15710 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15720 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
15730 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
15740 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
15750 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
15760 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
15770 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
15780 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
15790 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
157a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
157b0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
157c0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
157d0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
157e0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
157f0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
15800 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
15810 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
15820 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
15830 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
15840 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
15850 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
15860 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
15870 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
15880 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
15890 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
158a0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
158b0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
158c0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
158d0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
158e0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
158f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
15900 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
15910 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
15920 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
15930 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15940 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
15950 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15960 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
15970 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
15980 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
15990 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
159a0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
159b0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
159c0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
159d0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
159e0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
159f0 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
15a00 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
15a10 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
15a20 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15a30 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
15a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15a50 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
15a60 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
15a70 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15a80 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
15a90 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
15aa0 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
15ab0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
15ac0 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
15ad0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
15ae0 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
15af0 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
15b00 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
15b10 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15b20 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
15b30 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
15b40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
15b50 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
15b60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
15b70 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
15b80 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
15b90 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15ba0 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
15bb0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
15bc0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
15bd0 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
15be0 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
15bf0 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
15c00 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
15c10 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
15c20 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
15c30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
15c40 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
15c50 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
15c60 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
15c70 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
15c80 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
15c90 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15ca0 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
15cb0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
15cc0 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
15cd0 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
15ce0 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
15cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15d00 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
15d10 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
15d20 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
15d30 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
15d40 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
15d50 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
15d60 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
15d70 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
15d80 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
15d90 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
15da0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
15db0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
15dc0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
15dd0 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
15de0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15df0 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
15e00 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
15e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15e20 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
15e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15e40 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
15e50 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15e60 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15e70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15e80 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15e90 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
15ea0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15eb0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15ec0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15ed0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
15ee0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
15ef0 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
15f00 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
15f10 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
15f20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
15f30 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
15f40 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
15f50 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
15f60 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
15f70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
15f80 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
15f90 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15fa0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
15fb0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
15fc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15fd0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
15fe0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15ff0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
16000 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
16010 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
16020 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
16030 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
16040 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
16050 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
16060 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
16070 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
16080 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
16090 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
160a0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
160b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
160c0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
160d0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
160e0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
160f0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
16100 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16110 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
16120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16130 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
16140 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
16150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16160 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
16170 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16180 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
16190 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
161a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
161b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
161c0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
161d0 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
161e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
161f0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
16200 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
16210 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
16220 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
16230 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
16240 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
16250 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
16260 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
16270 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
16280 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
16290 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
162a0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
162b0 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
162c0 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
162d0 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
162e0 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
162f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
16300 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
16310 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
16320 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
16330 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
16340 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
16350 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
16360 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
16370 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
16380 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
16390 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
163a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
163b0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
163c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
163d0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
163e0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
163f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
16400 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
16410 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16420 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
16430 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
16440 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
16450 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16460 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16470 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
16480 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
16490 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
164a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
164b0 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
164c0 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
164d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
164e0 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
164f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
16500 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
16510 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
16520 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
16530 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
16540 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
16550 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
16560 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
16570 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
16580 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16590 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
165a0 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
165b0 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
165c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
165d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
165e0 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
165f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16600 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
16610 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16620 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
16630 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
16640 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
16650 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
16660 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16670 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
16680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16690 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
166a0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
166b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
166c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
166d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
166e0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
166f0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
16700 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16710 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
16720 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
16730 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
16740 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
16750 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
16760 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
16770 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
16780 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
16790 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
167a0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
167b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
167c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
167d0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
167e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
167f0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
16800 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16810 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
16820 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16830 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16840 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
16850 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
16860 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16870 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
16880 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
16890 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
168a0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
168b0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
168c0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
168d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
168e0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
168f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
16900 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
16910 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16920 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
16930 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
16940 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
16950 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
16960 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
16970 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
16980 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
16990 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
169a0 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
169b0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
169c0 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
169d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
169e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
169f0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
16a00 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
16a10 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
16a20 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
16a30 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
16a40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
16a50 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
16a60 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
16a70 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
16a80 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
16a90 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
16aa0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
16ab0 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
16ac0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
16ad0 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
16ae0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
16af0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
16b00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
16b10 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
16b20 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
16b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16b50 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
16b60 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
16b70 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
16b80 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
16b90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16ba0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
16bb0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
16bc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
16bd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16be0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
16bf0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
16c00 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
16c10 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
16c20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
16c30 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
16c40 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
16c50 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
16c60 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
16c70 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
16c80 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
16c90 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
16ca0 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
16cb0 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
16cc0 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
16cd0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
16ce0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
16cf0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
16d00 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
16d10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
16d20 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
16d30 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
16d40 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
16d50 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
16d60 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
16d70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16d80 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
16d90 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
16da0 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
16db0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16dc0 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
16dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
16de0 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
16df0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
16e00 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16e10 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
16e20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
16e30 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
16e40 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16e50 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
16e60 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
16e70 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
16e80 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
16e90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
16ea0 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
16eb0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16ec0 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
16ed0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
16ee0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
16ef0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
16f00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
16f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
16f20 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
16f30 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
16f40 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
16f50 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
16f60 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
16f70 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
16f80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
16f90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
16fa0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
16fb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
16fc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16fd0 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
16fe0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
16ff0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
17000 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
17010 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
17020 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
17030 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
17040 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
17050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17060 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
17070 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
17080 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
17090 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
170a0 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
170b0 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
170c0 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
170d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
170e0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
170f0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
17100 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17110 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17120 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
17130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
17140 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
17150 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17160 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17170 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
17180 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17190 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
171a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
171b0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
171c0 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
171d0 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
171e0 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
171f0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
17200 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
17210 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
17220 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
17230 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
17240 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
17250 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
17260 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
17270 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
17280 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
17290 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
172a0 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
172b0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
172c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
172d0 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
172e0 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
172f0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
17300 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
17310 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
17320 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
17330 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
17340 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
17350 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
17360 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
17370 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
17380 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
17390 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
173a0 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
173b0 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
173c0 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
173d0 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
173e0 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
173f0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
17400 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
17410 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
17420 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
17430 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17440 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
17450 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17460 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
17470 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17480 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
17490 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
174a0 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
174b0 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
174c0 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
174d0 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
174e0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
174f0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
17500 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17510 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
17520 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
17530 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17540 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
17550 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17560 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
17570 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
17580 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17590 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
175a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
175b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
175c0 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
175d0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
175e0 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
175f0 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
17600 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
17610 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
17620 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
17630 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
17640 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
17650 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
17660 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
17670 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
17680 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
17690 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
176a0 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
176b0 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
176c0 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
176d0 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
176e0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
176f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17700 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
17710 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
17720 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
17730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17740 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
17750 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
17760 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
17770 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
17780 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
17790 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
177a0 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
177b0 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
177c0 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
177d0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
177e0 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
177f0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
17800 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
17810 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
17820 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
17830 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
17840 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
17850 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
17860 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
17870 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
17880 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
17890 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
178a0 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
178b0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
178c0 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
178d0 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
178e0 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
178f0 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
17900 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17910 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
17920 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
17930 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
17940 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
17950 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
17960 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
17970 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17980 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
17990 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
179a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
179b0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
179c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
179d0 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
179e0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
179f0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
17a00 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
17a10 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
17a20 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
17a30 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17a40 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
17a50 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
17a60 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
17a70 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
17a80 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
17a90 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
17aa0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
17ab0 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
17ac0 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
17ad0 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
17ae0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17af0 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
17b00 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
17b10 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
17b20 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
17b30 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
17b40 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
17b50 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
17b60 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
17b70 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
17b80 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
17b90 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
17ba0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
17bb0 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
17bc0 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
17bd0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
17be0 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
17bf0 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
17c00 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
17c10 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
17c20 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
17c30 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
17c40 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
17c50 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
17c60 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
17c70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[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 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
17ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17cb0 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
17cc0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17cd0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17ce0 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
17cf0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
17d00 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
17d10 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
17d20 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
17d30 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
17d40 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
17d50 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
17d60 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
17d70 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
17d80 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
17d90 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
17da0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
17db0 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
17dc0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
17dd0 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
17de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17df0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
17e00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17e10 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17e20 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17e40 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
17e50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17e60 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17e70 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
17e80 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
17e90 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
17ea0 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
17eb0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
17ec0 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
17ed0 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
17ee0 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
17ef0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
17f00 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
17f10 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
17f20 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
17f30 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
17f40 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
17f50 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
17f60 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
17f70 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
17f80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17f90 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
17fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17fb0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17fd0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17fe0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17ff0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
18000 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
18010 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
18020 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
18030 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
18040 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
18050 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
18060 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
18070 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
18080 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
18090 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
180a0 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
180b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
180c0 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
180d0 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
180e0 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
180f0 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
18100 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
18110 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
18120 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
18130 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
18140 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
18150 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
18160 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
18170 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
18180 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
18190 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
181a0 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
181b0 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
181c0 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
181d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
181e0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
181f0 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
18200 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18210 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
18220 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
18230 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18240 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
18250 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
18260 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
18270 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
18280 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
18290 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
182a0 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
182b0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
182c0 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
182d0 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
182e0 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
182f0 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
18300 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
18310 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
18320 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
18330 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
18340 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
18350 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
18360 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
18370 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
18380 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
18390 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
183a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
183b0 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
183c0 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
183d0 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
183e0 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
183f0 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
18400 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
18410 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
18420 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
18430 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
18440 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
18450 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
18460 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
18470 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
18480 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
18490 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
184a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
184b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
184c0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
184d0 52 45 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  REF_SIZE]].** <d
184e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
184f0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 0a 2a  SORTERREF_SIZE.*
18500 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
18510 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
18520 46 5f 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63  F_SIZE option ac
18530 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70  cepts a single p
18540 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20 74  arameter.** of t
18550 79 70 65 20 28 69 6e 74 29 20 2d 20 74 68 65 20  ype (int) - the 
18560 6e 65 77 20 76 61 6c 75 65 20 6f 66 20 74 68 65  new value of the
18570 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
18580 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
18590 2e 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77 68  ..** Usually, wh
185a0 65 6e 20 53 51 4c 69 74 65 20 75 73 65 73 20 61  en SQLite uses a
185b0 6e 20 65 78 74 65 72 6e 61 6c 20 73 6f 72 74 20  n external sort 
185c0 74 6f 20 6f 72 64 65 72 20 72 65 63 6f 72 64 73  to order records
185d0 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
185e0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61   an ORDER BY cla
185f0 75 73 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73 20  use, all fields 
18600 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20  required by the 
18610 63 61 6c 6c 65 72 20 61 72 65 20 70 72 65 73 65  caller are prese
18620 6e 74 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f 72  nt in the.** sor
18630 74 65 64 20 72 65 63 6f 72 64 73 2e 20 48 6f 77  ted records. How
18640 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
18650 64 65 74 65 72 6d 69 6e 65 73 20 62 61 73 65 64  determines based
18660 20 6f 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64   on the declared
18670 20 74 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74 61   type.** of a ta
18680 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
18690 69 74 73 20 76 61 6c 75 65 73 20 61 72 65 20 6c  its values are l
186a0 69 6b 65 6c 79 20 74 6f 20 62 65 20 76 65 72 79  ikely to be very
186b0 20 6c 61 72 67 65 20 2d 20 6c 61 72 67 65 72 0a   large - larger.
186c0 2a 2a 20 74 68 61 6e 20 74 68 65 20 63 6f 6e 66  ** than the conf
186d0 69 67 75 72 65 64 20 73 6f 72 74 65 72 2d 72 65  igured sorter-re
186e0 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
186f0 65 73 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61 20  eshold - then a 
18700 72 65 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73 20  reference.** is 
18710 73 74 6f 72 65 64 20 69 6e 20 65 61 63 68 20 73  stored in each s
18720 6f 72 74 65 64 20 72 65 63 6f 72 64 20 61 6e 64  orted record and
18730 20 74 68 65 20 72 65 71 75 69 72 65 64 20 63 6f   the required co
18740 6c 75 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61 64  lumn values load
18750 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 64  ed.** from the d
18760 61 74 61 62 61 73 65 20 61 73 20 72 65 63 6f 72  atabase as recor
18770 64 73 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  ds are returned 
18780 69 6e 20 73 6f 72 74 65 64 20 6f 72 64 65 72 2e  in sorted order.
18790 20 54 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   The default.** 
187a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f  value for this o
187b0 70 74 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76 65  ption is to neve
187c0 72 20 75 73 65 20 74 68 69 73 20 6f 70 74 69 6d  r use this optim
187d0 69 7a 61 74 69 6f 6e 2e 20 53 70 65 63 69 66 79  ization. Specify
187e0 69 6e 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74 69  ing a .** negati
187f0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  ve value for thi
18800 73 20 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72 65  s option restore
18810 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  s the default be
18820 68 61 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69 73  haviour..** This
18830 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
18840 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
18850 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
18860 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
18870 49 54 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 45  ITE_ENABLE_SORTE
18880 52 5f 52 45 46 45 52 45 4e 43 45 53 5d 20 63 6f  R_REFERENCES] co
18890 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
188a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
188b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d  E_CONFIG_MEMDB_M
188c0 41 58 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  AXSIZE]].** <dt>
188d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
188e0 4d 44 42 5f 4d 41 58 53 49 5a 45 0a 2a 2a 20 3c  MDB_MAXSIZE.** <
188f0 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  dd>The SQLITE_CO
18900 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49  NFIG_MEMDB_MAXSI
18910 5a 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74  ZE option accept
18920 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
18930 65 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  eter.** [sqlite3
18940 5f 69 6e 74 36 34 5d 20 70 61 72 61 6d 65 74 65  _int64] paramete
18950 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 64  r which is the d
18960 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 73  efault maximum s
18970 69 7a 65 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65  ize for an in-me
18980 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
18990 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
189a0 73 71 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c  sqlite3_deserial
189b0 69 7a 65 28 29 5d 2e 20 20 54 68 69 73 20 64 65  ize()].  This de
189c0 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 0a 2a 2a  fault maximum.**
189d0 20 73 69 7a 65 20 63 61 6e 20 62 65 20 61 64 6a   size can be adj
189e0 75 73 74 65 64 20 75 70 20 6f 72 20 64 6f 77 6e  usted up or down
189f0 20 66 6f 72 20 69 6e 64 69 76 69 64 75 61 6c 20   for individual 
18a00 64 61 74 61 62 61 73 65 73 20 75 73 69 6e 67 20  databases using 
18a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
18a20 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  CNTL_SIZE_LIMIT]
18a30 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
18a40 6f 6e 74 72 6f 6c 7c 66 69 6c 65 2d 63 6f 6e 74  ontrol|file-cont
18a50 72 6f 6c 5d 2e 20 20 49 66 20 74 68 69 73 0a 2a  rol].  If this.*
18a60 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
18a70 73 65 74 74 69 6e 67 20 69 73 20 6e 65 76 65 72  setting is never
18a80 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
18a90 64 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20  default maximum 
18aa0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
18ab0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
18ac0 4d 45 4d 44 42 5f 44 45 46 41 55 4c 54 5f 4d 41  MEMDB_DEFAULT_MA
18ad0 58 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  XSIZE] compile-t
18ae0 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 49 66 20  ime option.  If 
18af0 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  that.** compile-
18b00 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6e  time option is n
18b10 6f 74 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  ot set, then the
18b20 20 64 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d   default maximum
18b30 20 69 73 20 31 30 37 33 37 34 31 38 32 34 2e 0a   is 1073741824..
18b40 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
18b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18b60 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
18b70 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
18b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18b90 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
18ba0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
18bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18bc0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
18bd0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
18be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18bf0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
18c00 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
18c10 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
18c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c30 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
18c40 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
18c50 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
18c60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c70 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
18c80 20 20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20         6  /* No 
18c90 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
18ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18cb0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
18cc0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
18cd0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
18ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18cf0 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
18d00 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
18d10 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
18d20 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
18d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
18d40 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
18d50 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
18d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18d70 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
18d80 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
18d90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18da0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18db0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
18dc0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
18dd0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
18de0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
18df0 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
18e00 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
18e10 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
18e20 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
18e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
18e40 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
18e50 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
18e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18e70 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
18e80 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
18e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18ea0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
18eb0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
18ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ed0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
18ee0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
18ef0 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
18f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f10 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
18f20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
18f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18f40 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
18f50 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
18f60 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
18f70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
18f90 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
18fa0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
18fb0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
18fc0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18fd0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
18fe0 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
18ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19000 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
19010 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
19020 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
19030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19040 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
19050 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
19060 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
19070 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt64 */.#define 
19080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
19090 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20  N32_HEAPSIZE    
190a0 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79    23  /* int nBy
190b0 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
190c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
190d0 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20  HE_HDRSZ        
190e0 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20  24  /* int *psz 
190f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19100 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20  E_CONFIG_PMASZ  
19110 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
19120 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   /* unsigned int
19130 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e   szPma */.#defin
19140 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19150 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20  STMTJRNL_SPILL  
19160 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e      26  /* int n
19170 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
19180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
19190 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  ALL_MALLOC      
191a0 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e    27  /* boolean
191b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
191c0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
191d0 52 45 46 5f 53 49 5a 45 20 20 20 20 20 20 32 38  REF_SIZE      28
191e0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
191f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19200 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41  _CONFIG_MEMDB_MA
19210 58 53 49 5a 45 20 20 20 20 20 20 20 32 39 20 20  XSIZE       29  
19220 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
19230 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
19240 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
19250 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
19260 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
19270 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
19280 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
19290 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
192a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
192b0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
192c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
192d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
192e0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
192f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19300 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
19310 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
19320 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
19330 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
19340 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
19350 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
19360 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19370 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
19380 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
19390 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
193a0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
193b0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
193c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
193d0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
193e0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
193f0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
19400 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
19410 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
19420 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
19430 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
19440 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
19450 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
19460 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
19470 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
19480 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
19490 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
194a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
194b0 4f 4f 4b 41 53 49 44 45 5d 5d 0a 2a 2a 20 3c 64  OOKASIDE]].** <d
194c0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
194d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
194e0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
194f0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
19500 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
19510 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
19520 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
19530 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
19540 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
19550 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
19560 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19570 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
19580 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
19590 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
195a0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
195b0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
195c0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
195d0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
195e0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
195f0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
19600 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
19610 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
19620 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19630 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
19640 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
19650 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
19660 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
19670 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
19680 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
19690 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
196a0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
196b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
196c0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
196d0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
196e0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
196f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19700 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19710 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
19720 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
19730 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
19740 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
19750 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
19760 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
19770 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
19780 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
19790 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
197a0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
197b0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
197c0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
197d0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
197e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
197f0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19800 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
19810 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
19820 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
19830 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
19840 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
19850 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
19860 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
19870 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
19880 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
19890 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
198a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
198b0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
198c0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
198d0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
198e0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
198f0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
19900 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
19910 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
19920 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
19930 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
19940 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
19950 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
19960 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
19970 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
19980 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
19990 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
199a0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
199b0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
199c0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
199d0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
199e0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
199f0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
19a00 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
19a10 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
19a20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
19a30 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19a40 5f 46 4b 45 59 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _FKEY]].** <dt>S
19a50 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19a60 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
19a70 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19a80 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19a90 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19aa0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
19ab0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
19ac0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
19ad0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
19ae0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19af0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19b00 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19b10 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19b20 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19b30 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
19b40 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
19b50 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
19b60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
19b70 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
19b80 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19b90 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
19ba0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19bb0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19bc0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
19bd0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
19be0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19bf0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19c00 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
19c10 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
19c20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
19c30 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
19c40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
19c50 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
19c60 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
19c70 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
19c80 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
19c90 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
19ca0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
19cb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19cc0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
19cd0 47 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  GER]].** <dt>SQL
19ce0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19cf0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
19d00 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19d10 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19d20 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19d30 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
19d40 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
19d50 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19d60 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19d70 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19d80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19d90 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
19da0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
19db0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
19dc0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
19dd0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
19de0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19df0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19e00 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
19e10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19e20 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
19e30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
19e40 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
19e50 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
19e60 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
19e70 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
19e80 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
19e90 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
19ea0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19eb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19ec0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
19ed0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19ee0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
19ef0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
19f00 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19f10 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19f20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
19f30 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
19f40 4b 45 4e 49 5a 45 52 5d 5d 0a 2a 2a 20 3c 64 74  KENIZER]].** <dt
19f50 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19f60 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
19f70 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
19f80 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19f90 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19fa0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
19fb0 65 0a 2a 2a 20 5b 66 74 73 33 5f 74 6f 6b 65 6e  e.** [fts3_token
19fc0 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
19fd0 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
19fe0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
19ff0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
1a000 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
1a010 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
1a020 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
1a030 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
1a040 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1a050 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
1a060 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
1a070 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
1a080 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
1a090 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
1a0a0 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
1a0b0 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
1a0c0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
1a0d0 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
1a0e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1a0f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1a100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1a110 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1a120 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
1a130 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1a140 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
1a150 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
1a160 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1a170 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
1a180 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
1a190 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
1a1a0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
1a1b0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
1a1c0 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
1a1d0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
1a1e0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
1a1f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a200 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a210 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
1a220 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
1a230 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a240 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
1a250 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
1a260 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
1a270 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
1a280 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
1a290 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1a2a0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
1a2b0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
1a2c0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
1a2d0 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
1a2e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1a2f0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1a300 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a310 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
1a320 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
1a330 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
1a340 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1a350 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
1a360 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
1a370 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
1a380 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1a390 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1a3a0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1a3b0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
1a3c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
1a3d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
1a3e0 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
1a3f0 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
1a400 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
1a410 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
1a420 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
1a430 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a440 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
1a450 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
1a460 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
1a470 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
1a480 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
1a490 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
1a4a0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
1a4b0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
1a4c0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
1a4d0 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
1a4e0 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
1a4f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
1a500 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1a510 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1a520 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1a530 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1a540 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1a550 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1a560 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
1a570 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a580 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
1a590 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
1a5a0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
1a5b0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
1a5c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a5d0 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
1a5e0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
1a5f0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
1a600 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
1a610 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
1a620 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1a630 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a640 4d 41 49 4e 44 42 4e 41 4d 45 5d 5d 20 3c 64 74  MAINDBNAME]] <dt
1a650 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a660 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
1a670 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
1a680 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1a690 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
1a6a0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
1a6b0 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
1a6c0 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
1a6d0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1a6e0 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
1a6f0 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
1a700 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
1a710 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
1a720 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
1a730 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
1a740 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
1a750 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
1a760 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
1a770 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
1a780 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
1a790 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
1a7a0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
1a7b0 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
1a7c0 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
1a7d0 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
1a7e0 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
1a7f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a800 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
1a810 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a820 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1a830 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
1a840 53 45 5d 5d 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c  SE]] .** <dt>SQL
1a850 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a860 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
1a870 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
1a880 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
1a890 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
1a8a0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
1a8b0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
1a8c0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1a8d0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
1a8e0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
1a8f0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
1a900 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
1a910 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
1a920 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
1a930 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
1a940 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
1a950 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
1a960 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
1a970 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
1a980 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
1a990 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
1a9a0 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
1a9b0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
1a9c0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
1a9d0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
1a9e0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
1a9f0 72 20 2d 20 70 6f 73 69 74 69 76 65 20 74 6f 20  r - positive to 
1aa00 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
1aa10 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
1aa20 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
1aa30 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
1aa40 20 74 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61 74   them, and negat
1aa50 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1aa60 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1aa70 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1aa80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1aa90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1aaa0 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
1aab0 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
1aac0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1aad0 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
1aae0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
1aaf0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
1ab00 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
1ab10 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
1ab20 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
1ab30 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
1ab40 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1ab50 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 5d  FIG_ENABLE_QPSG]
1ab60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1ab70 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1ab80 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28  G</dt>.** <dd>^(
1ab90 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  The SQLITE_DBCON
1aba0 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
1abb0 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
1abc0 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
1abd0 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c  ** the [query pl
1abe0 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20  anner stability 
1abf0 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47  guarantee] (QPSG
1ac00 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53  ).  When the QPS
1ac10 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20  G is active,.** 
1ac20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
1ac30 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ry statement wil
1ac40 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1ac50 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
1ac60 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
1ac70 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e   values of [boun
1ac80 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e  d parameters].)^
1ac90 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c   The QPSG disabl
1aca0 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70  es some query op
1acb0 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74  timizations.** t
1acc0 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20  hat look at the 
1acd0 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20  values of bound 
1ace0 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63  parameters, whic
1acf0 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20  h can make some 
1ad00 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65  queries.** slowe
1ad10 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47  r.  But the QPSG
1ad20 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61   has the advanta
1ad30 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69  ge of more predi
1ad40 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ctable behavior.
1ad50 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50    With.** the QP
1ad60 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74  SG active, SQLit
1ad70 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  e will always us
1ad80 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79  e the same query
1ad90 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65   plan in the fie
1ada0 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65  ld as.** was use
1adb0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
1adc0 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20   in the lab..** 
1add0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1ade0 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74 69  nt to this setti
1adf0 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ng is an integer
1ae00 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1ae10 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 51  isable .** the Q
1ae20 50 53 47 2c 20 70 6f 73 69 74 69 76 65 20 74 6f  PSG, positive to
1ae30 20 65 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f 72   enable QPSG, or
1ae40 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1ae50 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  ve the setting.*
1ae60 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65  * unchanged. The
1ae70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ae80 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1ae90 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1aea0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1aeb0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1aec0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1aed0 20 74 68 65 20 51 50 53 47 20 69 73 20 64 69 73   the QPSG is dis
1aee0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1aef0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
1af00 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64  is call..** </dd
1af10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1af20 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45  _DBCONFIG_TRIGGE
1af30 52 5f 45 51 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  R_EQP]] <dt>SQLI
1af40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47  TE_DBCONFIG_TRIG
1af50 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20  GER_EQP</dt>.** 
1af60 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c  <dd> By default,
1af70 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45   the output of E
1af80 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
1af90 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20  N commands does 
1afa0 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  not .** include 
1afb0 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f  output for any o
1afc0 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72  perations perfor
1afd0 6d 65 64 20 62 79 20 74 72 69 67 67 65 72 20 70  med by trigger p
1afe0 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a  rograms. This.**
1aff0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
1b000 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  to set or clear 
1b010 28 74 68 65 20 64 65 66 61 75 6c 74 29 20 61 20  (the default) a 
1b020 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e  flag that govern
1b030 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69  s this.** behavi
1b040 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  or. The first pa
1b050 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
1b060 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
1b070 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d   is an integer -
1b080 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
1b090 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f  enable output fo
1b0a0 72 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  r trigger progra
1b0b0 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64  ms, or zero to d
1b0c0 69 73 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72  isable it,.** or
1b0d0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1b0e0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1b0f0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1b100 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b110 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1b120 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1b130 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74  o which is writt
1b140 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f  en .** 0 or 1 to
1b150 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1b160 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69  r output-for-tri
1b170 67 67 65 72 73 20 68 61 73 20 62 65 65 6e 20 64  ggers has been d
1b180 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a  isabled - 0 if .
1b190 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73  ** it is not dis
1b1a0 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69  abled, 1 if it i
1b1b0 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  s.  .** </dd>.**
1b1c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1b1d0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1b1e0 42 41 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  BASE]] <dt>SQLIT
1b1f0 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1b200 5f 44 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a  _DATABASE</dt>.*
1b210 2a 20 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53  * <dd> Set the S
1b220 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1b230 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c  ESET_DATABASE fl
1b240 61 67 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a  ag and then run.
1b250 2a 2a 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f  ** [VACUUM] in o
1b260 72 64 65 72 20 74 6f 20 72 65 73 65 74 20 61 20  rder to reset a 
1b270 64 61 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f  database back to
1b280 20 61 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61   an empty databa
1b290 73 65 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63  se.** with no sc
1b2a0 68 65 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74  hema and no cont
1b2b0 65 6e 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ent. The followi
1b2c0 6e 67 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73  ng process works
1b2d0 20 65 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62   even for.** a b
1b2e0 61 64 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64  adly corrupted d
1b2f0 61 74 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a  atabase file:.**
1b300 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
1b310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b320 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c  nnection is newl
1b330 79 20 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73  y opened, make s
1b340 75 72 65 20 69 74 20 68 61 73 20 72 65 61 64 20  ure it has read 
1b350 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61  the.**      data
1b360 62 61 73 65 20 73 63 68 65 6d 61 20 62 79 20 70  base schema by p
1b370 72 65 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69  reparing then di
1b380 73 63 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75  scarding some qu
1b390 65 72 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a  ery against the.
1b3a0 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65  **      database
1b3b0 2c 20 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c  , or calling sql
1b3c0 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
1b3d0 6e 5f 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67  n_metadata(), ig
1b3e0 6e 6f 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20  noring any.**   
1b3f0 20 20 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73     errors.  This
1b400 20 73 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65   step is only ne
1b410 63 65 73 73 61 72 79 20 69 66 20 74 68 65 20 61  cessary if the a
1b420 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72  pplication desir
1b430 65 73 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20  es to keep.**   
1b440 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1b450 69 6e 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65  in WAL mode afte
1b460 72 20 74 68 65 20 72 65 73 65 74 20 69 66 20 69  r the reset if i
1b470 74 20 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64  t was in WAL mod
1b480 65 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  e before.**     
1b490 20 74 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a   the reset.  .**
1b4a0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62   <li> sqlite3_db
1b4b0 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49  _config(db, SQLI
1b4c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b4d0 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30  T_DATABASE, 1, 0
1b4e0 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69  );.** <li> [sqli
1b4f0 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b  te3_exec](db, "[
1b500 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20  VACUUM]", 0, 0, 
1b510 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  0);.** <li> sqli
1b520 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62  te3_db_config(db
1b530 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  , SQLITE_DBCONFI
1b540 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1b550 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c  , 0, 0);.** </ol
1b560 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73  >.** Because res
1b570 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73  etting a databas
1b580 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65  e is destructive
1b590 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c   and irreversibl
1b5a0 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73  e, the.** proces
1b5b0 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75  s requires the u
1b5c0 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75  se of this obscu
1b5d0 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69  re API and multi
1b5e0 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c  ple steps to hel
1b5f0 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74  p.** ensure that
1b600 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70   it does not hap
1b610 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e  pen by accident.
1b620 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1b630 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b640 56 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  VE]] <dt>SQLITE_
1b650 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b660 56 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  VE</dt>.** <dd>T
1b670 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1b680 49 47 5f 44 45 46 45 4e 53 49 56 45 20 6f 70 74  IG_DEFENSIVE opt
1b690 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72  ion activates or
1b6a0 20 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65   deactivates the
1b6b0 0a 2a 2a 20 22 64 65 66 65 6e 73 69 76 65 22 20  .** "defensive" 
1b6c0 66 6c 61 67 20 66 6f 72 20 61 20 64 61 74 61 62  flag for a datab
1b6d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1b6e0 20 57 68 65 6e 20 74 68 65 20 64 65 66 65 6e 73   When the defens
1b6f0 69 76 65 0a 2a 2a 20 66 6c 61 67 20 69 73 20 65  ive.** flag is e
1b700 6e 61 62 6c 65 64 2c 20 6c 61 6e 67 75 61 67 65  nabled, language
1b710 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 61   features that a
1b720 6c 6c 6f 77 20 6f 72 64 69 6e 61 72 79 20 53 51  llow ordinary SQ
1b730 4c 20 74 6f 20 0a 2a 2a 20 64 65 6c 69 62 65 72  L to .** deliber
1b740 61 74 65 6c 79 20 63 6f 72 72 75 70 74 20 74 68  ately corrupt th
1b750 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1b760 61 72 65 20 64 69 73 61 62 6c 65 64 2e 20 20 54  are disabled.  T
1b770 68 65 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66  he disabled.** f
1b780 65 61 74 75 72 65 73 20 69 6e 63 6c 75 64 65 20  eatures include 
1b790 62 75 74 20 61 72 65 20 6e 6f 74 20 6c 69 6d 69  but are not limi
1b7a0 74 65 64 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ted to the follo
1b7b0 77 69 6e 67 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  wing:.** <ul>.**
1b7c0 20 3c 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d   <li> The [PRAGM
1b7d0 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d  A writable_schem
1b7e0 61 3d 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  a=ON] statement.
1b7f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 5b 50 52  .** <li> The [PR
1b800 41 47 4d 41 20 6a 6f 75 72 6e 61 6c 5f 6d 6f 64  AGMA journal_mod
1b810 65 3d 4f 46 46 5d 20 73 74 61 74 65 6d 65 6e 74  e=OFF] statement
1b820 2e 0a 2a 2a 20 3c 6c 69 3e 20 57 72 69 74 65 73  ..** <li> Writes
1b830 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 5f   to the [sqlite_
1b840 64 62 70 61 67 65 5d 20 76 69 72 74 75 61 6c 20  dbpage] virtual 
1b850 74 61 62 6c 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  table..** <li> D
1b860 69 72 65 63 74 20 77 72 69 74 65 73 20 74 6f 20  irect writes to 
1b870 5b 73 68 61 64 6f 77 20 74 61 62 6c 65 73 5d 2e  [shadow tables].
1b880 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64  .** </ul>.** </d
1b890 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1b8a0 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41  E_DBCONFIG_WRITA
1b8b0 42 4c 45 5f 53 43 48 45 4d 41 5d 5d 20 3c 64 74  BLE_SCHEMA]] <dt
1b8c0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1b8d0 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1b8e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b8f0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b900 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1b910 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
1b920 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
1b930 20 74 68 65 0a 2a 2a 20 22 77 72 69 74 61 62 6c   the.** "writabl
1b940 65 5f 73 63 68 65 6d 61 22 20 66 6c 61 67 2e 20  e_schema" flag. 
1b950 54 68 69 73 20 68 61 73 20 74 68 65 20 73 61 6d  This has the sam
1b960 65 20 65 66 66 65 63 74 20 61 6e 64 20 69 73 20  e effect and is 
1b970 6c 6f 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61  logically equiva
1b980 6c 65 6e 74 0a 2a 2a 20 74 6f 20 73 65 74 74 69  lent.** to setti
1b990 6e 67 20 5b 50 52 41 47 4d 41 20 77 72 69 74 61  ng [PRAGMA writa
1b9a0 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 6f  ble_schema=ON] o
1b9b0 72 20 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62  r [PRAGMA writab
1b9c0 6c 65 5f 73 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a  le_schema=OFF]..
1b9d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1b9e0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 73 65  ument to this se
1b9f0 74 74 69 6e 67 20 69 73 20 61 6e 20 69 6e 74 65  tting is an inte
1ba00 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
1ba10 6f 20 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68  o disable .** th
1ba20 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d  e writable_schem
1ba30 61 2c 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  a, positive to e
1ba40 6e 61 62 6c 65 20 77 72 69 74 61 62 6c 65 5f 73  nable writable_s
1ba50 63 68 65 6d 61 2c 20 6f 72 20 6e 65 67 61 74 69  chema, or negati
1ba60 76 65 20 74 6f 0a 2a 2a 20 6c 65 61 76 65 20 74  ve to.** leave t
1ba70 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1ba80 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64  nged. The second
1ba90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1baa0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
1bab0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1bac0 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
1bad0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1bae0 65 20 77 68 65 74 68 65 72 20 74 68 65 20 77 72  e whether the wr
1baf0 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 0a 2a 2a  itable_schema.**
1bb00 20 69 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64   is enabled or d
1bb10 69 73 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e  isabled followin
1bb20 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20  g this call..** 
1bb30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1bb40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 45  LITE_DBCONFIG_LE
1bb50 47 41 43 59 5f 41 4c 54 45 52 5f 54 41 42 4c 45  GACY_ALTER_TABLE
1bb60 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
1bb70 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59  _DBCONFIG_LEGACY
1bb80 5f 41 4c 54 45 52 5f 54 41 42 4c 45 3c 2f 64 74  _ALTER_TABLE</dt
1bb90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1bba0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47  ITE_DBCONFIG_LEG
1bbb0 41 43 59 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ACY_ALTER_TABLE 
1bbc0 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
1bbd0 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
1bbe0 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ** the legacy be
1bbf0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 5b 41  havior of the [A
1bc00 4c 54 45 52 20 54 41 42 4c 45 20 52 45 4e 41 4d  LTER TABLE RENAM
1bc10 45 5d 20 63 6f 6d 6d 61 6e 64 20 73 75 63 68 20  E] command such 
1bc20 69 74 0a 2a 2a 20 62 65 68 61 76 65 73 20 61 73  it.** behaves as
1bc30 20 69 74 20 64 69 64 20 70 72 69 6f 72 20 74 6f   it did prior to
1bc40 20 5b 76 65 72 73 69 6f 6e 20 33 2e 32 34 2e 30   [version 3.24.0
1bc50 5d 20 28 32 30 31 38 2d 30 36 2d 30 34 29 2e 20  ] (2018-06-04). 
1bc60 20 53 65 65 20 74 68 65 0a 2a 2a 20 22 43 6f 6d   See the.** "Com
1bc70 70 61 74 69 62 69 6c 69 74 79 20 4e 6f 74 69 63  patibility Notic
1bc80 65 22 20 6f 6e 20 74 68 65 20 5b 41 4c 54 45 52  e" on the [ALTER
1bc90 20 54 41 42 4c 45 20 52 45 4e 41 4d 45 20 64 6f   TABLE RENAME do
1bca0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1bcb0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
1bcc0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 69 73  nformation. This
1bcd0 20 66 65 61 74 75 72 65 20 63 61 6e 20 61 6c 73   feature can als
1bce0 6f 20 62 65 20 74 75 72 6e 65 64 20 6f 6e 20 61  o be turned on a
1bcf0 6e 64 20 6f 66 66 0a 2a 2a 20 75 73 69 6e 67 20  nd off.** using 
1bd00 74 68 65 20 5b 50 52 41 47 4d 41 20 6c 65 67 61  the [PRAGMA lega
1bd10 63 79 5f 61 6c 74 65 72 5f 74 61 62 6c 65 5d 20  cy_alter_table] 
1bd20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 2f  statement..** </
1bd30 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1bd40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f  TE_DBCONFIG_DQS_
1bd50 44 4d 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  DML]].** <dt>SQL
1bd60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53  ITE_DBCONFIG_DQS
1bd70 5f 44 4d 4c 3c 2f 74 64 3e 0a 2a 2a 20 3c 64 64  _DML</td>.** <dd
1bd80 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  >The SQLITE_DBCO
1bd90 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 20 6f 70 74  NFIG_DQS_DML opt
1bda0 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72  ion activates or
1bdb0 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20   deactivates.** 
1bdc0 74 68 65 20 6c 65 67 61 63 79 20 5b 64 6f 75 62  the legacy [doub
1bdd0 6c 65 2d 71 75 6f 74 65 64 20 73 74 72 69 6e 67  le-quoted string
1bde0 20 6c 69 74 65 72 61 6c 5d 20 6d 69 73 66 65 61   literal] misfea
1bdf0 74 75 72 65 20 66 6f 72 20 44 4d 4c 20 73 74 61  ture for DML sta
1be00 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 6c 79 2c 20  tement.** only, 
1be10 74 68 61 74 20 69 73 20 44 45 4c 45 54 45 2c 20  that is DELETE, 
1be20 49 4e 53 45 52 54 2c 20 53 45 4c 45 43 54 2c 20  INSERT, SELECT, 
1be30 61 6e 64 20 55 50 44 41 54 45 20 73 74 61 74 65  and UPDATE state
1be40 6d 65 6e 74 73 2e 20 54 68 65 0a 2a 2a 20 64 65  ments. The.** de
1be50 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74  fault value of t
1be60 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 64  his setting is d
1be70 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
1be80 20 5b 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d 0a   [-DSQLITE_DQS].
1be90 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
1bea0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e  option..** </dd>
1beb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1bec0 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c  DBCONFIG_DQS_DDL
1bed0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
1bee0 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44  _DBCONFIG_DQS_DD
1bef0 4c 3c 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68  L</td>.** <dd>Th
1bf00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1bf10 47 5f 44 51 53 20 6f 70 74 69 6f 6e 20 61 63 74  G_DQS option act
1bf20 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1bf30 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67  vates.** the leg
1bf40 61 63 79 20 5b 64 6f 75 62 6c 65 2d 71 75 6f 74  acy [double-quot
1bf50 65 64 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ed string litera
1bf60 6c 5d 20 6d 69 73 66 65 61 74 75 72 65 20 66 6f  l] misfeature fo
1bf70 72 20 44 44 4c 20 73 74 61 74 65 6d 65 6e 74 73  r DDL statements
1bf80 2c 0a 2a 2a 20 73 75 63 68 20 61 73 20 43 52 45  ,.** such as CRE
1bf90 41 54 45 20 54 41 42 4c 45 20 61 6e 64 20 43 52  ATE TABLE and CR
1bfa0 45 41 54 45 20 49 4e 44 45 58 2e 20 54 68 65 0a  EATE INDEX. The.
1bfb0 2a 2a 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ** default value
1bfc0 20 6f 66 20 74 68 69 73 20 73 65 74 74 69 6e 67   of this setting
1bfd0 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62   is determined b
1bfe0 79 20 74 68 65 20 5b 2d 44 53 51 4c 49 54 45 5f  y the [-DSQLITE_
1bff0 44 51 53 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  DQS].** compile-
1c000 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1c010 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1c020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c030 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
1c040 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
1c050 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
1c060 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
1c070 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
1c080 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
1c090 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
1c0a0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
1c0b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c0c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
1c0d0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
1c0e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c100 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
1c110 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
1c120 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
1c130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c140 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1c150 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
1c160 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
1c170 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c180 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1c190 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
1c1a0 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
1c1b0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c1c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
1c1d0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
1c1e0 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
1c1f0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c200 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c210 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
1c220 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
1c230 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c240 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c250 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20  G_TRIGGER_EQP   
1c260 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20          1008 /* 
1c270 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c280 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c290 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1c2a0 53 45 20 20 20 20 20 20 20 20 31 30 30 39 20 2f  SE        1009 /
1c2b0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c2c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c2d0 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 20  ONFIG_DEFENSIVE 
1c2e0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31 30              1010
1c2f0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c310 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45  BCONFIG_WRITABLE
1c320 5f 53 43 48 45 4d 41 20 20 20 20 20 20 20 31 30  _SCHEMA       10
1c330 31 31 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  11 /* int int* *
1c340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c350 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59  _DBCONFIG_LEGACY
1c360 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1c370 31 30 31 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1012 /* int int*
1c380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c390 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f  TE_DBCONFIG_DQS_
1c3a0 44 4d 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  DML             
1c3b0 20 20 31 30 31 33 20 2f 2a 20 69 6e 74 20 69 6e    1013 /* int in
1c3c0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c3d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51  LITE_DBCONFIG_DQ
1c3e0 53 5f 44 44 4c 20 20 20 20 20 20 20 20 20 20 20  S_DDL           
1c3f0 20 20 20 20 31 30 31 34 20 2f 2a 20 69 6e 74 20      1014 /* int 
1c400 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c410 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c420 4d 41 58 20 20 20 20 20 20 20 20 20 20 20 20 20  MAX             
1c430 20 20 20 20 20 20 31 30 31 34 20 2f 2a 20 4c 61        1014 /* La
1c440 72 67 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a  rgest DBCONFIG *
1c450 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1c460 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
1c470 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
1c480 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
1c490 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c4a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c4b0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
1c4c0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
1c4d0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1c4e0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
1c4f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1c500 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
1c510 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
1c520 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
1c530 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
1c540 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
1c550 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
1c560 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51  atibility..*/.SQ
1c570 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1c580 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1c590 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
1c5a0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
1c5b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c5c0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
1c5d0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
1c5e0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
1c5f0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
1c600 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
1c610 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
1c620 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
1c630 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
1c640 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
1c650 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
1c660 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
1c670 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
1c680 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
1c690 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
1c6a0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
1c6b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
1c6c0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
1c6d0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
1c6e0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
1c6f0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
1c700 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
1c710 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
1c720 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
1c730 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
1c740 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
1c750 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
1c760 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
1c770 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
1c780 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
1c790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c7a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c7b0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
1c7c0 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
1c7d0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
1c7e0 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
1c7f0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
1c800 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
1c810 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
1c820 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
1c830 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
1c840 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
1c850 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
1c860 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1c870 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
1c880 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
1c890 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1c8a0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1c8b0 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
1c8c0 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
1c8d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c8e0 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
1c8f0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1c900 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
1c910 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
1c920 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
1c930 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
1c940 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
1c950 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
1c960 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
1c970 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
1c980 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1c990 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
1c9a0 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
1c9b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1c9c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c9d0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
1c9e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1c9f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
1ca00 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
1ca10 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1ca20 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
1ca30 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
1ca40 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
1ca50 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
1ca60 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
1ca70 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
1ca80 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
1ca90 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1caa0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
1cab0 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
1cac0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1cad0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
1cae0 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
1caf0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
1cb00 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
1cb10 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
1cb20 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1cb30 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
1cb40 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
1cb50 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
1cb60 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
1cb70 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
1cb80 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
1cb90 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
1cba0 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
1cbb0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1cbc0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1cbd0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
1cbe0 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
1cbf0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
1cc00 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
1cc10 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1cc20 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
1cc30 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
1cc40 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
1cc50 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1cc60 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
1cc70 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1cc80 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
1cc90 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
1cca0 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
1ccb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1ccc0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
1ccd0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
1cce0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
1ccf0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
1cd00 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
1cd10 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
1cd20 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
1cd30 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
1cd40 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
1cd50 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
1cd60 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
1cd70 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1cd80 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1cd90 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
1cda0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
1cdb0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
1cdc0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
1cdd0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
1cde0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
1cdf0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
1ce00 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
1ce10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1ce20 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1ce30 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
1ce40 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
1ce50 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
1ce60 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
1ce70 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
1ce80 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
1ce90 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
1cea0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
1ceb0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
1cec0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
1ced0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
1cee0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
1cef0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
1cf00 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
1cf10 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
1cf20 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
1cf30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1cf40 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
1cf50 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
1cf60 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1cf70 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
1cf80 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
1cf90 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
1cfa0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
1cfb0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
1cfc0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
1cfd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1cfe0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
1cff0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1d000 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
1d010 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1d020 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1d030 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1d040 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1d050 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1d060 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1d070 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1d080 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1d090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1d0a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1d0b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1d0c0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1d0d0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1d0e0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1d0f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1d100 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1d110 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1d120 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1d130 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1d140 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1d150 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1d160 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1d170 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1d180 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
1d190 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1d1a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
1d1b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1d1c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1d1d0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
1d1e0 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
1d1f0 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
1d200 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d210 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d220 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1d230 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
1d240 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
1d250 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1d260 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
1d270 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
1d280 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
1d290 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
1d2a0 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
1d2b0 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
1d2c0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1d2d0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1d2e0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65   void sqlite3_se
1d2f0 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1d300 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c  wid(sqlite3*,sql
1d310 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
1d320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1d330 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
1d340 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1d350 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d360 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1d370 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d380 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1d390 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
1d3a0 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
1d3b0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
1d3c0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
1d3d0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
1d3e0 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
1d3f0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
1d400 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d410 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
1d420 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1d430 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
1d440 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1d450 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1d460 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
1d470 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
1d480 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
1d490 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1d4a0 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
1d4b0 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
1d4c0 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
1d4d0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1d4e0 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
1d4f0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
1d500 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
1d510 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
1d520 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
1d530 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
1d540 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
1d550 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
1d560 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1d570 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1d580 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
1d590 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
1d5a0 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
1d5b0 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
1d5c0 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
1d5d0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1d5e0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
1d5f0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
1d600 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
1d610 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1d620 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
1d630 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
1d640 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
1d650 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
1d660 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
1d670 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
1d680 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
1d690 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
1d6a0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
1d6b0 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
1d6c0 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
1d6d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1d6e0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1d6f0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
1d700 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
1d710 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
1d720 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
1d730 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
1d740 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
1d750 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1d760 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
1d770 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
1d780 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
1d790 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
1d7a0 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
1d7b0 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
1d7c0 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
1d7d0 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
1d7e0 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
1d7f0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
1d800 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
1d810 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
1d820 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1d830 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
1d840 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
1d850 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
1d860 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
1d870 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
1d880 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
1d890 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
1d8a0 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
1d8b0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
1d8c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1d8d0 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
1d8e0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
1d8f0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
1d900 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d910 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1d920 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
1d930 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
1d940 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
1d950 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
1d960 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
1d970 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
1d980 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
1d990 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
1d9a0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1d9b0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1d9c0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
1d9d0 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
1d9e0 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
1d9f0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
1da00 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
1da10 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
1da20 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
1da30 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1da40 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
1da50 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
1da60 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
1da70 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1da80 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1da90 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
1daa0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
1dab0 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
1dac0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
1dad0 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
1dae0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
1daf0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
1db00 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
1db10 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
1db20 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1db30 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
1db40 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
1db50 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
1db60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1db70 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
1db80 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
1db90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1dba0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1dbb0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
1dbc0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
1dbd0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1dbe0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1dbf0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1dc00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dc10 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1dc20 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1dc30 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1dc40 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1dc50 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1dc60 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1dc70 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a  meaningful..**.*
1dc80 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c  * See also:.** <
1dc90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ul>.** <li> the 
1dca0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1dcb0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1dcc0 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ace.** <li> the 
1dcd0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1dce0 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74  ragma].** <li> t
1dcf0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1dd00 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c  L function].** <
1dd10 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65  li> the [data_ve
1dd20 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a  rsion pragma].**
1dd30 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
1dd40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1dd50 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1dd60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1dd70 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1dd80 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1dd90 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1dda0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1ddb0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1ddc0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1ddd0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1dde0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1ddf0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1de00 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1de10 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1de20 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1de30 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1de40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1de50 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1de60 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1de70 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1de80 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1de90 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1dea0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1deb0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1dec0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1ded0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1dee0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1def0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1df00 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1df10 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1df20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1df30 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1df40 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1df50 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1df60 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1df70 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1df80 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1df90 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1dfa0 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1dfb0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1dfc0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1dfd0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1dfe0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1dff0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  unted..**.** The
1e000 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1e010 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74 65  changes(D)] inte
1e020 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1e030 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ts the number.**
1e040 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63 68   of rows that ch
1e050 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51 4c  anged due to SQL
1e060 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 61   statement run a
1e070 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65 0a  gainst database.
1e080 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  ** connection D.
1e090 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62 79    Any changes by
1e0a0 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 20   other database 
1e0b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65 20  connections are 
1e0c0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20 64  ignored..** To d
1e0d0 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61 67  etect changes ag
1e0e0 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73 65  ainst a database
1e0f0 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65 72   file from other
1e100 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
1e110 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68 65  nections use the
1e120 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65   [PRAGMA data_ve
1e130 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 6f  rsion] command o
1e140 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  r the.** [SQLITE
1e150 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
1e160 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ION] [file contr
1e170 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 61  ol]..** .** If a
1e180 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1e190 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1e1a0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1e1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e1c0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1e1d0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1e1e0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1e1f0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
1e200 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
1e210 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1e220 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a   meaningful..**.
1e230 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20  ** See also:.** 
1e240 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  <ul>.** <li> the
1e250 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1e260 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  s()] interface.*
1e270 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e  * <li> the [coun
1e280 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1e290 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63  ].** <li> the [c
1e2a0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1e2b0 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74  ction].** <li> t
1e2c0 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e  he [data_version
1e2d0 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e   pragma].** <li>
1e2e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
1e2f0 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d  TL_DATA_VERSION]
1e300 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 0a   [file control].
1e310 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
1e320 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1e330 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1e340 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1e350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1e360 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1e370 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
1e380 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1e390 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1e3a0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
1e3b0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
1e3c0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
1e3d0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1e3e0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1e3f0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1e400 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1e410 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1e420 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1e430 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1e440 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1e450 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1e460 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1e470 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1e480 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1e490 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1e4a0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1e4b0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1e4c0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1e4d0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1e4e0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1e4f0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1e500 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1e510 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1e520 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1e530 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1e540 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1e550 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1e560 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e570 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1e580 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1e590 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1e5a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e5b0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1e5c0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1e5d0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1e5e0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1e5f0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1e600 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1e610 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1e620 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1e630 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1e640 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1e650 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1e660 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1e670 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1e680 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1e690 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1e6a0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1e6b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1e6c0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1e6d0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1e6e0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1e6f0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1e700 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1e710 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1e720 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1e730 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1e740 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1e750 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1e760 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1e770 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1e780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e790 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1e7a0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1e7b0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1e7c0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1e7d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1e7e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e7f0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1e800 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1e810 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1e820 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1e830 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1e840 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1e850 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1e860 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1e870 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1e880 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1e890 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1e8a0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1e8b0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1e8c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e8d0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1e8e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1e8f0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1e900 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1e910 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1e920 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1e930 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1e940 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1e950 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e960 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1e970 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e980 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1e990 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1e9a0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1e9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1e9c0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1e9d0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1e9e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1e9f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1ea00 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1ea10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1ea20 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a  all returns..*/.
1ea30 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1ea40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ea50 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1ea60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1ea70 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1ea80 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1ea90 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1eaa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1eab0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1eac0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1ead0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1eae0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1eaf0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1eb00 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1eb10 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1eb20 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1eb30 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1eb40 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1eb50 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1eb60 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1eb70 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1eb80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1eb90 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1eba0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1ebb0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1ebc0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1ebd0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1ebe0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1ebf0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1ec00 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1ec10 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1ec20 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1ec30 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1ec40 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1ec50 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1ec60 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1ec70 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1ec80 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1ec90 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1eca0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1ecb0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1ecc0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1ecd0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1ece0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1ecf0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1ed00 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1ed10 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1ed20 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1ed30 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1ed40 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1ed50 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1ed60 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1ed70 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1ed80 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1ed90 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1eda0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1edb0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1edc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1edd0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1ede0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1edf0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1ee00 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1ee10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1ee20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1ee30 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1ee40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1ee50 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1ee60 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1ee70 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1ee80 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1ee90 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1eea0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1eeb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1eec0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1eed0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1eee0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1eef0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1ef00 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1ef10 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1ef20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1ef30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1ef40 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1ef50 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1ef60 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1ef70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1ef80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1ef90 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1efa0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1efb0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1efc0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1efd0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1efe0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1eff0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1f000 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1f010 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1f020 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1f030 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1f040 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1f050 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1f060 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1f070 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1f080 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1f090 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1f0a0 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  rder..*/.SQLITE_
1f0b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1f0c0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1f0d0 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54  har *sql);.SQLIT
1f0e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1f0f0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1f100 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1f110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f120 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1f130 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1f140 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1f150 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1f160 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1f170 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1f180 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1f190 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1f1a0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1f1b0 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1f1c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1f1d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1f1e0 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1f1f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1f200 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1f210 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1f220 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1f230 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1f240 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1f250 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1f260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1f270 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1f280 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1f290 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1f2a0 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1f2b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1f2c0 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1f2d0 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1f2e0 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1f2f0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1f300 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1f310 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1f320 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1f330 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1f340 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1f350 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1f360 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1f370 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1f380 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1f390 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1f3a0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1f3b0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1f3c0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1f3d0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1f3e0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1f3f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1f400 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1f410 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1f420 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1f430 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1f440 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1f450 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1f460 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1f470 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1f480 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1f490 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1f4a0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1f4b0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1f4c0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1f4d0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1f4e0 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1f4f0 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1f500 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1f510 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1f520 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1f530 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1f540 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1f550 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1f560 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1f570 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1f580 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1f590 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1f5a0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1f5b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1f5c0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1f5d0 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1f5e0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1f5f0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1f600 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1f610 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1f620 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1f630 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1f640 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1f650 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1f660 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1f670 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1f680 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1f690 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1f6a0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1f6b0 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1f6c0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1f6d0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1f6e0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1f6f0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1f700 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1f710 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1f720 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1f730 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1f740 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1f750 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1f760 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1f770 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1f780 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1f790 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1f7a0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1f7b0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1f7c0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1f7d0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1f7e0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1f7f0 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1f800 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1f810 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1f820 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1f830 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1f840 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1f850 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1f860 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1f870 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1f880 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1f890 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1f8a0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1f8b0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1f8c0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1f8d0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1f8e0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1f8f0 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1f900 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1f910 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1f920 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1f930 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1f940 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1f950 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1f960 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1f970 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1f980 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1f990 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1f9a0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1f9b0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1f9c0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1f9d0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1f9e0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1f9f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1fa00 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1fa10 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1fa20 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1fa30 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1fa40 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1fa50 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1fa60 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1fa70 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1fa80 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1fa90 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1faa0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1fab0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1fac0 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1fad0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1fae0 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1faf0 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1fb00 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1fb10 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1fb20 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1fb30 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1fb40 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1fb50 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1fb60 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1fb70 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1fb80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fb90 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1fba0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1fbb0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1fbc0 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1fbd0 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1fbe0 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1fbf0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1fc00 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1fc10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1fc20 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1fc30 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1fc40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1fc50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1fc60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fc70 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1fc80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1fc90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1fca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1fcb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1fcc0 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1fcd0 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1fce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1fcf0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1fd00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1fd10 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1fd20 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1fd30 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1fd40 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1fd50 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1fd60 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1fd70 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1fd80 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1fd90 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1fda0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1fdb0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1fdc0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1fdd0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1fde0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1fdf0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1fe00 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1fe10 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1fe20 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1fe30 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1fe40 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1fe50 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1fe60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1fe70 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1fe80 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1fe90 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1fea0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1feb0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1fec0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1fed0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1fee0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1fef0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1ff00 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1ff10 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1ff20 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1ff30 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ff40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1ff50 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1ff60 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1ff70 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1ff80 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1ff90 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1ffa0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1ffb0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1ffc0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1ffd0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1ffe0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1fff0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
20000 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
20010 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c  _timeout].*/.SQL
20020 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
20030 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
20040 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
20050 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
20060 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
20070 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
20080 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
20090 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
200a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
200b0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
200c0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
200d0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
200e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
200f0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
20100 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
20110 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
20120 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
20130 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
20140 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
20150 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
20160 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
20170 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
20180 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
20190 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
201a0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
201b0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
201c0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
201d0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
201e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
201f0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
20200 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
20210 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
20220 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
20230 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
20240 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
20250 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
20260 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
20270 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
20280 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
20290 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
202a0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
202b0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
202c0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
202d0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
202e0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
202f0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
20300 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
20310 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
20320 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
20330 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
20340 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
20350 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
20360 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
20370 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
20380 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
20390 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
203a0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
203b0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
203c0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
203d0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
203e0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
203f0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
20400 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
20410 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
20420 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
20430 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
20440 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
20450 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
20460 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
20470 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
20480 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
20490 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
204a0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
204b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
204c0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
204d0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
204e0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
204f0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
20500 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
20510 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
20520 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
20530 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20540 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
20550 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
20560 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
20570 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
20580 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
20590 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
205a0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
205b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
205c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
205d0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
205e0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
205f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
20600 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
20610 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
20620 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
20630 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
20640 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
20650 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
20660 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
20670 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
20680 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
20690 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
206a0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
206b0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
206c0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
206d0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
206e0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
206f0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
20700 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
20710 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
20720 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
20730 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
20740 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
20750 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
20760 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
20770 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
20780 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
20790 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
207a0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
207b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
207c0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
207d0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
207e0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
207f0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
20800 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
20810 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
20820 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
20830 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
20840 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
20850 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
20860 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
20870 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
20880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
20890 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
208a0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
208b0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
208c0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
208d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
208e0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
208f0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
20900 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
20910 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
20920 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
20930 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
20940 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
20950 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
20960 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
20970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
20980 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
20990 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
209a0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
209b0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
209c0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
209d0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
209e0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
209f0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
20a00 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
20a10 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
20a20 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
20a30 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
20a40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20a50 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
20a60 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
20a70 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
20a80 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
20a90 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
20aa0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
20ab0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
20ac0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
20ad0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
20ae0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
20af0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
20b00 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
20b10 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
20b20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
20b30 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
20b40 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
20b50 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
20b60 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
20b70 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
20b80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20b90 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
20ba0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
20bb0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
20bc0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
20bd0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
20be0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
20bf0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
20c00 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
20c10 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
20c20 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
20c30 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
20c40 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
20c50 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
20c60 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
20c70 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
20c80 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
20c90 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
20ca0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20cb0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
20cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
20cd0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
20ce0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
20cf0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
20d00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20d10 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
20d20 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
20d30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
20d40 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
20d50 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
20d60 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
20d70 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
20d80 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
20d90 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
20da0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
20db0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
20dc0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
20dd0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
20de0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
20df0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
20e00 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
20e10 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
20e20 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
20e30 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
20e40 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
20e50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
20e60 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
20e70 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
20e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e90 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
20ea0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
20eb0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
20ec0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
20ed0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
20ee0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
20ef0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
20f00 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
20f10 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
20f20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20f30 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
20f40 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
20f50 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
20f60 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  ns from.** the s
20f70 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
20f80 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75  printf() .** plu
20f90 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
20fa0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
20fb0 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25  ormats ([%q], [%
20fc0 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25  Q], [%w], and [%
20fd0 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20  z])..** See the 
20fe0 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66  [built-in printf
20ff0 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
21000 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a  n for details..*
21010 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21020 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
21030 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
21040 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
21050 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
21060 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
21070 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
21080 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
21090 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
210a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
210b0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
210c0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
210d0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
210e0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
210f0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
21100 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
21110 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
21120 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20  _malloc64()] is 
21130 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
21140 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
21150 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21160 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
21170 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
21180 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
21190 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
211a0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
211b0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
211c0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
211d0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
211e0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
211f0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
21200 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
21210 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
21220 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
21230 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
21240 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
21250 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
21260 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
21270 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
21280 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
21290 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
212a0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
212b0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
212c0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
212d0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
212e0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
212f0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
21300 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
21310 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
21320 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
21330 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
21340 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
21350 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
21360 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
21370 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
21380 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
21390 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
213a0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
213b0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
213c0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
213d0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
213e0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
213f0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
21400 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
21410 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
21420 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
21430 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
21440 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
21450 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
21460 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
21470 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
21480 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
21490 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
214a0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
214b0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
214c0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
214d0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
214e0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
214f0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
21500 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
21510 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
21520 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
21530 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
21540 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
21550 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
21560 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
21570 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
21580 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
21590 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
215a0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
215b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
215c0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
215d0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
215e0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53  rintf()..**.** S
215f0 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74  ee also:  [built
21600 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b  -in printf()], [
21610 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e  printf() SQL fun
21620 63 74 69 6f 6e 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ction].*/.SQLITE
21630 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
21640 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
21650 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
21660 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
21670 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
21680 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
21690 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
216a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
216b0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
216c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
216d0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
216e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
216f0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
21700 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
21710 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
21720 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
21730 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
21740 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
21750 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
21760 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
21770 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
21780 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
21790 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
217a0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
217b0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
217c0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
217d0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
217e0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
217f0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
21800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
21810 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
21820 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
21830 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
21840 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
21850 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
21860 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
21870 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
21880 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
21890 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
218a0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
218b0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
218c0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
218d0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
218e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
218f0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
21900 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
21910 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
21920 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
21930 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
21940 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
21950 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
21960 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
21970 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
21980 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
21990 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
219a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
219b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
219c0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
219d0 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
219e0 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
219f0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
21a00 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
21a10 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
21a20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
21a30 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
21a40 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
21a50 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
21a60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
21a70 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
21a80 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
21a90 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
21aa0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
21ab0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
21ac0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
21ad0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
21ae0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
21af0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
21b00 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
21b10 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
21b20 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
21b30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
21b40 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
21b50 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
21b60 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
21b70 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
21b80 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
21b90 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
21ba0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
21bb0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
21bc0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
21bd0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
21be0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
21bf0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
21c00 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
21c10 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
21c20 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
21c30 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
21c40 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
21c50 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
21c60 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
21c70 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
21c80 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
21c90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
21ca0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
21cb0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
21cc0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
21cd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
21ce0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
21cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
21d00 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
21d10 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
21d20 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
21d30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
21d40 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
21d50 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
21d60 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
21d70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
21d80 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
21d90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
21da0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
21db0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
21dc0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
21dd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
21de0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
21df0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21e00 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21e10 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
21e20 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
21e30 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
21e40 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
21e50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
21e60 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
21e70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21e80 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
21e90 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
21ea0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
21eb0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
21ec0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
21ed0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
21ee0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
21ef0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
21f00 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
21f10 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
21f20 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
21f30 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
21f40 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
21f50 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
21f60 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
21f70 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
21f80 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
21f90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21fa0 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
21fb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
21fc0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
21fd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21fe0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
21ff0 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
22000 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
22010 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
22020 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
22030 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22040 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
22050 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
22060 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
22070 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
22080 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
22090 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
220a0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
220b0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
220c0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
220d0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
220e0 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
220f0 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
22100 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
22110 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
22120 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
22130 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
22140 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
22150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
22160 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
22170 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
22180 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
22190 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
221a0 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
221b0 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
221c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
221d0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
221e0 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
221f0 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
22200 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
22210 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
22220 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
22230 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
22240 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
22250 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
22260 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
22270 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
22280 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
22290 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
222a0 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
222b0 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
222c0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
222d0 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
222e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
222f0 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
22300 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
22310 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
22320 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
22330 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
22340 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
22350 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
22360 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
22370 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
22380 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
22390 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
223a0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
223b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
223c0 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
223d0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
223e0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
223f0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
22400 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
22410 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
22420 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
22430 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
22440 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
22450 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
22460 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
22470 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
22480 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
22490 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
224a0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
224b0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
224c0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
224d0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
224e0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
224f0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
22500 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
22510 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
22520 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
22530 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
22540 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
22550 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
22560 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
22570 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
22580 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22590 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
225a0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
225b0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
225c0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
225d0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
225e0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
225f0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
22600 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
22610 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
22620 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
22630 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
22640 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
22650 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
22660 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
22670 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
22680 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
22690 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
226a0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
226b0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
226c0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
226d0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
226e0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
226f0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
22700 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
22710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
22720 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
22730 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
22740 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
22750 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
22760 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
22770 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
22780 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
22790 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
227a0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
227b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
227c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
227d0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
227e0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
227f0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
22800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
22810 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
22820 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
22830 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
22840 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
22850 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
22860 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
22870 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
22880 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
22890 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
228a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
228b0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54  lloc(int);.SQLIT
228c0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
228d0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
228e0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51  ite3_uint64);.SQ
228f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
22900 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
22910 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
22920 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
22930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76  ite3_realloc64(v
22940 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
22950 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
22960 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
22970 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  ree(void*);.SQLI
22980 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75  TE_API sqlite3_u
22990 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
229a0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
229b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
229c0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
229d0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
229e0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
229f0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
22a00 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
22a10 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
22a20 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
22a30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
22a40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
22a50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
22a60 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
22a70 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
22a80 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
22a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
22aa0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
22ab0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
22ac0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
22ad0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
22ae0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
22af0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
22b00 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
22b10 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
22b20 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
22b30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
22b40 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
22b50 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
22b60 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
22b70 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
22b80 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
22b90 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
22ba0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
22bb0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
22bc0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
22bd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
22be0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22bf0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
22c00 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
22c10 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
22c20 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
22c30 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
22c40 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
22c50 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
22c60 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
22c70 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
22c80 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
22c90 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
22ca0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
22cb0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
22cc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
22cd0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
22ce0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
22cf0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
22d00 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
22d10 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
22d20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
22d30 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
22d40 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
22d50 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
22d60 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
22d70 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
22d80 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
22d90 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
22da0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
22db0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
22dc0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
22dd0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
22de0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
22df0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
22e00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
22e10 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
22e20 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
22e30 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
22e40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
22e50 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
22e60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
22e70 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
22e80 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
22e90 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
22ea0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
22eb0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
22ec0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
22ed0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
22ee0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
22ef0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
22f00 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
22f10 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
22f20 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
22f30 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
22f40 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
22f50 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
22f60 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
22f70 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
22f80 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
22f90 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
22fa0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
22fb0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
22fc0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
22fd0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
22fe0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
22ff0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
23000 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
23010 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
23020 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
23030 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
23040 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
23050 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
23060 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
23070 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
23080 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
23090 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
230a0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
230b0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
230c0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
230d0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
230e0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
230f0 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
23100 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
23110 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
23120 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
23130 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
23140 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
23150 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
23160 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
23170 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
23180 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
23190 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
231a0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
231b0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
231c0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
231d0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
231e0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
231f0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
23200 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
23210 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
23220 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
23230 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
23240 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
23250 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
23260 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
23270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23280 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
23290 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
232a0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
232b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45  D: sqlite3.** KE
232c0 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69  YWORDS: {authori
232d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a  zer callback}.**
232e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
232f0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
23300 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23310 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
23320 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
23330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
23340 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
23350 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
23360 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
23370 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
23380 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
23390 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
233a0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
233b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
233c0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
233d0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
233e0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
233f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23400 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
23410 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b  _prepare16()], [
23420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23430 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  6_v2()],.** and 
23440 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23450 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76  16_v3()].  ^At v
23460 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
23470 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
23480 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
23490 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
234a0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
234b0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
234c0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
234d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
234e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
234f0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
23500 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
23510 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
23520 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
23530 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
23540 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
23550 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
23560 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
23570 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
23580 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
23590 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
235a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
235b0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
235c0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
235d0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
235e0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
235f0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
23600 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
23610 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
23620 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
23630 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23640 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
23650 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
23660 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
23670 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
23680 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
23690 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
236a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
236b0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
236c0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
236d0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
236e0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
236f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
23700 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
23710 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
23720 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
23730 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
23740 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
23750 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
23760 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
23770 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
23780 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
23790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
237a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
237b0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
237c0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
237d0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
237e0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
237f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
23800 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
23810 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
23820 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
23830 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
23840 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
23850 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
23860 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
23870 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
23880 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
23890 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
238a0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
238b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
238c0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
238d0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
238e0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
238f0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
23900 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
23910 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
23920 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
23930 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
23940 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
23950 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
23960 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
23970 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69   either NULL poi
23980 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65  nters or zero-te
23990 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
239a0 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  .** that contain
239b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
239c0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
239d0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
239e0 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63  rized..** Applic
239f0 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61  ations must alwa
23a00 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74  ys be prepared t
23a10 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55  o encounter a NU
23a20 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e  LL pointer in an
23a30 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72  y.** of the thir
23a40 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69  d through the si
23a50 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f  xth parameters o
23a60 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  f the authorizat
23a70 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
23a80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
23a90 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
23aa0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
23ab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
23ac0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
23ad0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
23ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23af0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
23b00 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
23b10 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
23b20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
23b30 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
23b40 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
23b50 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
23b60 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
23b70 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
23b80 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
23b90 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
23ba0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
23bb0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
23bc0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
23bd0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
23be0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
23bf0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68   a table..** ^Wh
23c00 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65  en a table is re
23c10 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53  ferenced by a [S
23c20 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f  ELECT] but no co
23c30 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a  lumn values are.
23c40 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  ** extracted fro
23c50 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f  m that table (fo
23c60 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71  r example in a q
23c70 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45  uery like.** "SE
23c80 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52  LECT count(*) FR
23c90 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68  OM tab") then th
23ca0 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  e [SQLITE_READ] 
23cb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23cc0 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ack.** is invoke
23cd0 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20  d once for that 
23ce0 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c  table with a col
23cf0 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73  umn name that is
23d00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23d10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
23d20 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
23d30 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
23d40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
23d50 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
23d60 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
23d70 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
23d80 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
23d90 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
23da0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
23db0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
23dc0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
23dd0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
23de0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
23df0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
23e00 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
23e10 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
23e20 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
23e30 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
23e40 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
23e50 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
23e60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
23e70 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
23e80 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
23e90 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
23ea0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
23eb0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
23ec0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
23ed0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
23ee0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
23ef0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
23f00 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
23f10 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
23f20 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
23f30 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
23f40 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
23f50 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
23f60 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
23f70 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
23f80 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
23f90 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
23fa0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
23fb0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
23fc0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
23fd0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
23fe0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
23ff0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
24000 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
24010 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
24020 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
24030 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
24040 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
24050 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
24060 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
24070 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
24080 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
24090 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
240a0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
240b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
240c0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
240d0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
240e0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
240f0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
24100 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
24110 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
24120 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
24130 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
24140 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
24150 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
24160 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
24170 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
24180 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
24190 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
241a0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
241b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
241c0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
241d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
241e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
241f0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
24200 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
24210 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
24220 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
24230 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
24240 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
24250 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
24260 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
24270 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
24280 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
24290 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
242a0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
242b0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
242c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
242d0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
242e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
242f0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
24300 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
24310 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
24320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24330 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
24340 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
24350 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
24360 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
24370 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
24380 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
24390 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
243a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
243b0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
243c0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
243d0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
243e0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
243f0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
24400 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
24410 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
24420 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
24430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
24440 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
24450 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
24460 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
24470 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
24480 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
24490 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
244a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
244b0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
244c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
244d0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
244e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
244f0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
24500 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
24510 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
24520 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
24530 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
24540 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
24550 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
24560 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
24570 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
24580 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
24590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
245a0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
245b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
245c0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
245d0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
245e0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
245f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24600 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24610 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
24620 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
24630 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
24640 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
24650 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
24660 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
24670 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
24680 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24690 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
246a0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
246b0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
246c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
246d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
246e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
246f0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
24700 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
24710 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
24720 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
24730 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
24740 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
24750 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
24760 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
24770 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
24780 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24790 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
247a0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
247b0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
247c0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
247d0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
247e0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
247f0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
24800 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
24810 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
24820 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
24830 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
24840 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
24850 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
24860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
24870 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
24880 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
24890 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
248a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
248b0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
248c0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
248d0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
248e0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
248f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24900 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
24910 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
24920 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
24930 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
24940 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
24950 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
24960 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
24970 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
24980 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
24990 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
249a0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
249b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
249c0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
249d0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
249e0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
249f0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
24a00 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
24a10 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
24a20 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
24a30 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
24a40 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
24a50 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
24a60 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
24a70 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
24a80 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
24a90 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
24aa0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
24ab0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
24ac0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
24ad0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
24ae0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
24af0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
24b00 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
24b10 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
24b20 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
24b30 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
24b40 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
24b50 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
24b60 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
24b70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24b80 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
24b90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
24ba0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
24bb0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
24bc0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
24bd0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
24be0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
24bf0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
24c00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
24c10 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
24c20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
24c30 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
24c40 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
24c50 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
24c60 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
24c70 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
24c80 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
24c90 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
24ca0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
24cb0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
24cc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24cd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24ce0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
24cf0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
24d00 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
24d10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
24d20 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
24d30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24d40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24d50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24d60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
24d70 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
24d80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24d90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24da0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24db0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
24dc0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
24dd0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24de0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24df0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24e00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24e10 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
24e20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24e30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24e40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24e50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24e60 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
24e70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
24e80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24ea0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
24eb0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
24ec0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
24ed0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24ef0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
24f00 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
24f10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24f20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24f30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24f40 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
24f50 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
24f60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24f70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24f90 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
24fa0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
24fb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24fc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24fe0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
24ff0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
25000 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
25010 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
25020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
25030 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
25040 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
25050 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
25060 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
25070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
25080 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
25090 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
250a0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
250b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
250c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
250d0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
250e0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
250f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
25100 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
25110 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
25120 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
25130 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
25140 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
25150 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
25160 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
25170 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
25180 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
25190 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
251a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
251b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
251c0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
251d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
251e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
251f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
25200 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
25210 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
25220 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
25230 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
25240 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
25250 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
25260 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
25270 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
25280 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
25290 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
252a0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
252b0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
252c0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
252d0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
252e0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
252f0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
25300 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
25310 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
25320 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
25330 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
25340 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
25350 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
25360 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
25370 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
25380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25390 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
253a0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
253b0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
253c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
253d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
253e0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
253f0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
25400 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
25410 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
25420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25430 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
25440 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
25450 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
25460 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
25470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25480 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
25490 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
254a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
254b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
254c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
254d0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
254e0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
254f0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
25500 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
25510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
25520 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
25530 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
25540 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
25550 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
25560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
25570 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
25580 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
25590 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
255a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
255b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
255c0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
255d0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
255e0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
255f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
25600 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
25610 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
25620 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
25630 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
25640 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
25650 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
25660 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
25670 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
25680 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
25690 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
256a0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
256b0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
256c0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
256d0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
256e0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
256f0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
25700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
25710 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
25720 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
25730 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
25740 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
25750 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
25760 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25770 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
25780 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
25790 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
257a0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
257b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
257c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
257d0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
257e0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
257f0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
25800 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
25810 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
25820 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
25830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25840 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
25850 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
25860 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
25870 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
25880 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
25890 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
258a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
258b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
258c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
258d0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
258e0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
258f0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
25900 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
25910 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25920 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
25930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25940 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
25950 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
25960 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
25970 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
25980 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
25990 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
259a0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
259b0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
259c0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
259d0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
259e0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
259f0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
25a00 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
25a10 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
25a20 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
25a30 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
25a40 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
25a50 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
25a60 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
25a70 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
25a80 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
25a90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
25aa0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
25ab0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
25ac0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
25ad0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
25ae0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
25af0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
25b00 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
25b10 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
25b20 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
25b30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
25b40 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
25b50 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
25b60 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
25b70 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
25b80 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
25b90 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
25ba0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
25bb0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
25bc0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
25bd0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
25be0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
25bf0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
25c00 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
25c10 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
25c20 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
25c30 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
25c40 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
25c50 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
25c60 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
25c70 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
25c80 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
25c90 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
25ca0 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
25cb0 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
25cc0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
25cd0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
25ce0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
25cf0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25d00 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
25d10 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
25d20 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
25d30 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
25d40 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a  ck.  Invoking.**
25d50 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25d60 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71  _trace()] or [sq
25d70 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25d80 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68  ] will cancel th
25d90 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c  e.** profile cal
25da0 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45  lback..*/.SQLITE
25db0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
25dc0 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
25dd0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
25de0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
25df0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
25e00 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
25e10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
25e20 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
25e30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
25e40 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
25e50 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
25e60 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
25e70 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
25e80 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
25e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
25ea0 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
25eb0 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
25ec0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
25ed0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
25ee0 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
25ef0 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
25f00 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
25f10 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
25f20 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
25f30 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
25f40 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67  ogic.  The M arg
25f50 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
25f60 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
25f70 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52  M,X,P)] is an OR
25f80 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
25f90 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
25fa0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
25fb0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
25fc0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25fd0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
25fe0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
25ff0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
26000 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
26010 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
26020 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
26030 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
26040 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
26050 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
26060 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
26070 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
26080 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
26090 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
260a0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
260b0 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
260c0 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
260d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
260e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
260f0 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
26100 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
26110 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
26120 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
26130 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
26140 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
26150 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
26160 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
26170 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
26180 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
26190 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
261a0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
261b0 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
261c0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
261d0 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
261e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
261f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26200 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
26210 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
26220 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
26230 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
26240 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
26250 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
26260 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
26270 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
26280 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
26290 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
262a0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
262b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
262c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
262d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
262e0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
262f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
26300 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
26310 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
26320 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
26330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26340 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
26350 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
26360 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
26370 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
26380 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
26390 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
263a0 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
263b0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
263c0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
263d0 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
263e0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
263f0 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
26400 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
26410 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
26420 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
26430 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
26440 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
26450 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
26460 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26470 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
26480 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
26490 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
264a0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
264b0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
264c0 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
264d0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
264e0 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
264f0 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
26500 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
26510 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
26520 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
26530 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
26540 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
26550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26560 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
26570 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
26580 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
26590 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
265a0 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
265b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
265c0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
265d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
265e0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
265f0 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
26600 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
26610 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
26620 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
26630 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
26640 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
26650 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
26660 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
26670 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
26680 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
26690 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
266a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
266b0 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
266c0 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
266d0 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
266e0 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
266f0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
26700 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
26710 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26720 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
26730 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
26740 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
26750 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
26760 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
26770 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
26780 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
26790 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
267a0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
267b0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
267c0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
267d0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
267e0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
267f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
26800 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
26810 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
26820 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
26830 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
26840 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
26850 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
26860 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
26870 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
26880 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
26890 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
268a0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
268b0 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
268c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
268d0 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
268e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
268f0 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
26900 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
26910 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
26920 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
26930 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
26940 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
26950 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
26960 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
26970 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
26980 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
26990 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
269a0 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
269b0 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
269c0 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
269d0 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
269e0 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
269f0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
26a00 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
26a10 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
26a20 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
26a30 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
26a40 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
26a50 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
26a60 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
26a70 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
26a80 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
26a90 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
26aa0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
26ab0 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
26ac0 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
26ad0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
26ae0 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
26af0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
26b00 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
26b10 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
26b20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
26b30 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
26b40 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
26b50 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
26b60 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
26b70 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
26b80 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
26b90 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
26ba0 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
26bb0 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
26bc0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
26bd0 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
26be0 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
26bf0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
26c00 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
26c10 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
26c20 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
26c30 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
26c40 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
26c50 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
26c60 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
26c70 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
26c80 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
26c90 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
26ca0 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
26cb0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
26cc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
26cd0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
26ce0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
26cf0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
26d00 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
26d10 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
26d20 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
26d30 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
26d40 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
26d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26d60 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
26d70 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
26d80 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
26d90 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
26da0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
26db0 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
26dc0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
26dd0 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
26de0 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
26df0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
26e00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  I int sqlite3_tr
26e10 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
26e20 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
26e30 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
26e40 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
26e50 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
26e60 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
26e70 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
26e80 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
26e90 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
26ea0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
26eb0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
26ec0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
26ed0 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
26ee0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
26ef0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
26f00 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
26f10 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
26f20 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
26f30 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
26f40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
26f50 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
26f60 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
26f70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
26f80 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
26f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
26fa0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
26fb0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
26fc0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
26fd0 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
26fe0 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
26ff0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
27000 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
27010 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
27020 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
27030 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
27040 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
27050 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
27060 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
27070 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
27080 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
27090 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
270a0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
270b0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
270c0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
270d0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
270e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
270f0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
27100 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
27110 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
27120 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
27130 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
27140 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
27150 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
27160 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
27170 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
27180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
27190 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
271a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
271b0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
271c0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
271d0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
271e0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
271f0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
27200 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
27210 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
27220 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
27230 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
27240 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
27250 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
27260 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
27270 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
27280 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
27290 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
272a0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
272b0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
272c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
272d0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
272e0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
272f0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
27300 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
27310 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
27320 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
27330 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
27340 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
27350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27360 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
27370 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
27380 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
27390 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
273a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
273b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
273c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
273d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
273e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
273f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
27400 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
27410 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
27420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
27430 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
27440 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
27450 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
27460 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
27470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27480 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
27490 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
274a0 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
274b0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
274c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
274d0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
274e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
274f0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
27500 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
27510 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
27520 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27530 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
27540 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
27550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27560 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
27570 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
27580 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
27590 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
275a0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
275b0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
275c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
275d0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
275e0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
275f0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
27600 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
27610 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
27620 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
27630 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
27640 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27650 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
27660 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
27670 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
27680 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
27690 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
276a0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
276b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
276c0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
276d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
276e0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
276f0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
27700 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
27710 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
27720 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
27730 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
27740 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
27750 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
27760 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
27770 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
27780 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
27790 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
277a0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
277b0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
277c0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
277d0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
277e0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
277f0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
27800 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
27810 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
27820 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
27830 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
27840 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
27850 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
27860 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
27870 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27880 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
27890 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
278a0 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
278b0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
278c0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
278d0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
278e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
278f0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
27900 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
27910 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
27920 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
27930 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
27940 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
27950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27960 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
27970 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
27980 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
27990 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
279a0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
279b0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
279c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
279d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
279e0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
279f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
27a00 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
27a10 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
27a20 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
27a30 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
27a40 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
27a50 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
27a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
27a70 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
27a80 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
27a90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
27aa0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
27ab0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
27ac0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
27ad0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
27ae0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
27af0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
27b00 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
27b10 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
27b20 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
27b30 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
27b40 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
27b50 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
27b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
27b70 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
27b80 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
27b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
27ba0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
27bb0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
27bc0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
27bd0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
27be0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
27bf0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
27c00 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
27c10 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
27c20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
27c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
27c40 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
27c50 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
27c60 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
27c70 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
27c80 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
27c90 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
27ca0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
27cb0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
27cc0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
27cd0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
27ce0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
27cf0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
27d00 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
27d10 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
27d20 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
27d30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
27d40 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
27d50 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
27d60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
27d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27d80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27d90 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
27da0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
27db0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
27dc0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
27dd0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
27de0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
27df0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
27e00 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
27e10 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
27e30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
27e40 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
27e50 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
27e60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27e70 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
27e80 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
27e90 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
27ea0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
27eb0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
27ec0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
27ed0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
27ee0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
27ef0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
27f00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
27f10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
27f20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
27f30 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
27f40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
27f50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
27f60 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
27f70 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
27f80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
27f90 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
27fa0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
27fb0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
27fc0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
27fd0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
27fe0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
27ff0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
28000 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
28010 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
28020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
28030 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
28040 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
28050 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
28060 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
28070 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
28080 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
28090 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
280a0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
280b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
280c0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
280d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
280e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
280f0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
28100 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
28110 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
28120 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
28130 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
28140 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
28150 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
28160 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
28170 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
28180 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
28190 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
281a0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
281b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
281c0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
281d0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
281e0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
281f0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
28200 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
28210 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
28220 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28230 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
28240 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
28250 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
28260 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
28270 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
28280 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
28290 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
282a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
282b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
282c0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
282d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
282e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
282f0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
28300 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
28310 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
28320 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
28330 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
28340 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
28350 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
28360 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
28370 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
28380 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
28390 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
283a0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
283b0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
283c0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
283d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
283e0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
283f0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
28400 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
28410 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
28420 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
28430 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
28440 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
28450 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
28460 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
28470 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
28480 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
28490 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
284a0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
284b0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
284c0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
284d0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
284e0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
284f0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
28500 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
28510 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
28520 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
28530 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
28540 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
28550 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
28560 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
28570 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
28580 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
28590 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
285a0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
285b0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
285c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
285d0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
285e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
285f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
28600 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
28610 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
28620 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
28630 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
28640 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
28650 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
28660 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
28670 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
28680 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
28690 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
286a0 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
286b0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
286c0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
286d0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
286e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
286f0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
28700 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
28710 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
28720 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
28730 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
28740 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
28750 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
28760 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
28770 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
28780 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
28790 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
287a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
287b0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
287c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49  e option..** URI
287d0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
287e0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
287f0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
28800 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
28810 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
28820 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
28830 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
28840 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
28850 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
28860 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
28870 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
28880 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
28890 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
288a0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
288b0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
288c0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
288d0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
288e0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
288f0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
28900 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
28910 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
28920 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
28930 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
28940 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
28950 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
28960 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
28970 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
28980 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
28990 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
289a0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
289b0 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
289c0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
289d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
289e0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
289f0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
28a00 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
28a10 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
28a20 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
28a30 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
28a40 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
28a50 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
28a60 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
28a70 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
28a80 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
28a90 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
28aa0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
28ab0 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
28ac0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
28ad0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
28ae0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
28af0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
28b00 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
28b10 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
28b20 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
28b30 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
28b40 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
28b50 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
28b60 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
28b70 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
28b80 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
28b90 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
28ba0 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
28bb0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
28bc0 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
28bd0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
28be0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
28bf0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
28c00 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
28c10 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
28c20 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
28c30 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
28c40 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
28c50 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
28c60 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
28c70 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
28c80 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
28c90 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
28ca0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
28cb0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
28cc0 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
28cd0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
28ce0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
28cf0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
28d00 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
28d10 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
28d20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
28d30 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
28d40 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
28d50 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
28d60 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
28d70 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
28d80 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
28d90 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
28da0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
28db0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
28dc0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
28dd0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
28de0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
28df0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
28e00 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
28e10 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
28e20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
28e30 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
28e40 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
28e50 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
28e60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
28e70 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
28e80 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
28e90 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
28ea0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28eb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
28ec0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
28ed0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
28ee0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
28ef0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
28f00 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
28f10 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
28f20 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
28f30 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
28f40 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
28f50 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
28f60 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
28f70 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
28f80 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
28f90 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
28fa0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
28fb0 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
28fc0 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
28fd0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
28fe0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
28ff0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
29000 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
29010 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
29020 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
29030 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
29040 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
29050 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
29060 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
29070 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
29080 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
29090 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
290a0 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
290b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
290c0 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
290d0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
290e0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
290f0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
29100 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
29110 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
29120 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
29130 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
29140 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
29150 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
29160 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
29170 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
29180 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
29190 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
291a0 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
291b0 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
291c0 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
291d0 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
291e0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
291f0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
29200 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
29210 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
29220 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
29230 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
29240 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
29250 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
29260 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
29270 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
29280 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29290 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
292a0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
292b0 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
292c0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
292d0 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
292e0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
292f0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
29300 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
29310 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
29320 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
29330 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
29340 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
29350 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
29360 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
29370 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
29380 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
29390 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
293a0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
293b0 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
293c0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
293d0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
293e0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
293f0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
29400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29410 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
29420 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
29430 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
29440 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
29450 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
29460 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
29470 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
29480 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
29490 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
294a0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
294b0 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
294c0 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
294d0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
294e0 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
294f0 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
29500 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
29510 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
29520 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
29530 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
29540 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
29550 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
29560 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
29570 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
29580 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
29590 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
295a0 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
295b0 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
295c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
295d0 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
295e0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
295f0 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
29600 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
29610 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
29620 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
29630 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
29640 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
29650 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
29660 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
29670 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
29680 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
29690 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
296a0 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
296b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
296c0 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
296d0 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
296e0 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
296f0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
29700 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
29710 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
29720 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
29730 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
29740 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
29750 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
29760 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
29770 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
29780 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
29790 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
297a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
297b0 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
297c0 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
297d0 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
297e0 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
297f0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
29800 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
29810 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
29820 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
29830 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
29840 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
29850 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
29860 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
29870 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
29880 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
29890 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
298a0 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
298b0 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
298c0 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
298d0 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
298e0 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
298f0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29900 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
29910 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
29920 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
29930 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
29940 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
29950 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
29960 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
29970 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
29980 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
29990 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
299a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
299b0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
299c0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
299d0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
299e0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
299f0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
29a00 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
29a10 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
29a20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
29a30 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
29a40 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
29a50 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
29a60 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
29a70 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
29a80 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
29a90 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
29aa0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
29ab0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
29ac0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
29ad0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
29ae0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
29af0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
29b00 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
29b10 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
29b20 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
29b30 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
29b40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
29b50 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
29b60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
29b70 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
29b80 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
29b90 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
29ba0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
29bb0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
29bc0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
29bd0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
29be0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
29bf0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
29c00 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
29c10 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
29c20 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
29c30 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
29c40 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
29c50 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
29c60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
29c70 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
29c80 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
29c90 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
29ca0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
29cb0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
29cc0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
29cd0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
29ce0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
29cf0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
29d00 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
29d10 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
29d20 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
29d30 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
29d40 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
29d50 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
29d60 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
29d70 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
29d80 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
29d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
29da0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
29db0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
29dc0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
29dd0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
29de0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
29df0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
29e00 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
29e10 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
29e20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
29e30 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
29e40 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
29e50 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
29e60 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
29e70 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
29e80 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
29e90 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
29ea0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
29eb0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
29ec0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
29ed0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
29ee0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
29ef0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
29f00 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
29f10 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
29f20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
29f30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
29f40 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
29f50 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
29f60 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
29f70 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
29f80 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
29f90 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
29fa0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
29fb0 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
29fc0 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
29fd0 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
29fe0 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
29ff0 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
2a000 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
2a010 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
2a020 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
2a030 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
2a040 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
2a050 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
2a060 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
2a070 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
2a080 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
2a090 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
2a0a0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
2a0b0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
2a0c0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
2a0d0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
2a0e0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
2a0f0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
2a100 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
2a110 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
2a120 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
2a130 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
2a140 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
2a150 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
2a160 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
2a170 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
2a180 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
2a190 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
2a1a0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
2a1b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
2a1c0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
2a1d0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
2a1e0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
2a1f0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
2a200 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
2a210 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
2a220 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
2a230 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
2a240 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
2a250 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
2a260 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
2a270 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
2a280 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
2a290 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a2a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
2a2b0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
2a2c0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
2a2d0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
2a2e0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
2a2f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
2a300 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
2a310 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
2a320 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
2a330 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
2a340 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
2a350 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
2a360 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
2a370 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
2a380 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
2a390 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
2a3a0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
2a3b0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
2a3c0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
2a3d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
2a3e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a3f0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
2a400 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
2a410 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
2a420 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
2a430 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
2a440 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
2a450 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
2a460 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
2a470 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
2a480 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
2a490 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
2a4a0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
2a4b0 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
2a4c0 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
2a4d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a4e0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2a4f0 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54  ectory].*/.SQLIT
2a500 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a510 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
2a520 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
2a530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
2a540 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
2a550 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
2a560 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
2a570 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
2a580 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
2a590 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a5a0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
2a5b0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
2a5c0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
2a5d0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
2a5e0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
2a5f0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
2a600 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
2a610 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
2a620 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
2a640 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
2a650 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
2a660 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
2a670 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
2a680 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
2a690 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
2a6a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
2a6b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
2a6c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
2a6d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a6e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
2a6f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
2a700 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
2a710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a720 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
2a730 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
2a740 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
2a750 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
2a760 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
2a770 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
2a780 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
2a790 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
2a7a0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
2a7b0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
2a7c0 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
2a7d0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
2a7e0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
2a7f0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
2a800 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
2a810 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2a820 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
2a830 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
2a840 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
2a850 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
2a860 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
2a870 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
2a880 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
2a890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
2a8a0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
2a8b0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
2a8c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
2a8d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
2a8e0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
2a8f0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
2a900 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2a910 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
2a920 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2a930 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
2a940 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
2a950 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
2a960 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
2a970 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
2a980 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
2a990 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
2a9a0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
2a9b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
2a9c0 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
2a9d0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
2a9e0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
2a9f0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
2aa00 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
2aa10 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
2aa20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2aa30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
2aa40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2aa50 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2aa60 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
2aa70 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
2aa80 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
2aa90 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
2aaa0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
2aab0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
2aac0 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
2aad0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
2aae0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
2aaf0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
2ab00 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2ab10 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
2ab20 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
2ab30 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
2ab40 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
2ab50 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
2ab60 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
2ab70 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
2ab80 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
2ab90 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
2aba0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
2abb0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
2abc0 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
2abd0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
2abe0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
2abf0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
2ac00 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
2ac10 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
2ac20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
2ac30 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
2ac40 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
2ac50 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
2ac60 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
2ac70 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
2ac80 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
2ac90 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
2aca0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
2acb0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
2acc0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
2acd0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
2ace0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
2acf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
2ad00 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
2ad10 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
2ad20 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
2ad30 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
2ad40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2ad50 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
2ad60 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
2ad70 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
2ad80 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
2ad90 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
2ada0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2adb0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
2adc0 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
2add0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
2ade0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
2adf0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
2ae00 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
2ae10 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
2ae20 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
2ae30 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
2ae40 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
2ae50 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
2ae60 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
2ae70 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
2ae80 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
2ae90 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
2aea0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
2aeb0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
2aec0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
2aed0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2aee0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2aef0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2af00 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
2af10 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  rable..**.** See
2af20 20 74 68 65 20 5b 55 52 49 20 66 69 6c 65 6e 61   the [URI filena
2af30 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  me] documentatio
2af40 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2af50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
2af60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2af70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2af80 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
2af90 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
2afa0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
2afb0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
2afc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2afd0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
2afe0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2aff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
2b000 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
2b010 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
2b020 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2b030 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
2b040 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
2b050 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2b060 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
2b070 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
2b080 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
2b090 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
2b0a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
2b0b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2b0c0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
2b0d0 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
2b0e0 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
2b0f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
2b100 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
2b110 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2b120 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
2b130 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
2b140 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
2b150 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
2b160 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
2b170 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
2b180 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b190 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
2b1a0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
2b1b0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
2b1c0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
2b1d0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
2b1e0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2b1f0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
2b200 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
2b210 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
2b220 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
2b230 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  * The values ret
2b240 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2b250 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64 2f 6f  _errcode() and/o
2b260 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 74  r.** sqlite3_ext
2b270 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 20  ended_errcode() 
2b280 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77 69 74  might change wit
2b290 68 20 65 61 63 68 20 41 50 49 20 63 61 6c 6c 2e  h each API call.
2b2a0 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 65 72  .** Except, ther
2b2b0 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 65 72  e are some inter
2b2c0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 67  faces that are g
2b2d0 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65 76  uaranteed to nev
2b2e0 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  er.** change the
2b2f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 65 72   value of the er
2b300 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 65  ror code.  The e
2b310 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 65 72  rror-code preser
2b320 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ving.** interfac
2b330 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  es are:.**.** <u
2b340 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  l>.** <li> sqlit
2b350 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  e3_errcode().** 
2b360 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 78 74  <li> sqlite3_ext
2b370 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
2b380 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
2b390 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69 3e  errmsg().** <li>
2b3a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
2b3b0 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  6().** </ul>.**.
2b3c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b3d0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
2b3e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
2b3f0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
2b400 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
2b410 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
2b420 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
2b430 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2b440 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
2b450 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2b460 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2b470 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2b480 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2b490 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
2b4a0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
2b4b0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
2b4c0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
2b4d0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
2b4e0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
2b4f0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
2b500 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
2b510 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
2b520 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2b530 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
2b540 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
2b550 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
2b560 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
2b570 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
2b580 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
2b590 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
2b5a0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
2b5b0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
2b5c0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
2b5d0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
2b5e0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
2b5f0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
2b600 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
2b610 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
2b620 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
2b630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
2b640 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
2b650 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
2b660 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
2b670 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
2b680 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
2b690 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
2b6a0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
2b6b0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
2b6c0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
2b6d0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
2b6e0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
2b6f0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
2b700 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
2b710 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
2b720 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
2b730 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
2b740 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
2b750 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
2b760 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
2b770 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
2b780 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
2b790 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
2b7a0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
2b7b0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
2b7c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b7d0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
2b7e0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
2b7f0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
2b800 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
2b810 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
2b820 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
2b830 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
2b840 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
2b850 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
2b860 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
2b870 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
2b880 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
2b890 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
2b8a0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
2b8b0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
2b8c0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
2b8d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
2b8e0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
2b8f0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
2b900 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
2b910 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
2b920 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
2b930 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
2b940 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
2b950 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
2b960 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
2b970 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b980 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
2b990 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
2b9a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b9b0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2b9c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
2b9d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API 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 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ba10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ba20 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
2ba30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2ba40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ba50 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
2ba60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ba70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ba80 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
2ba90 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
2baa0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
2bab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bac0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
2bad0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
2bae0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
2baf0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
2bb00 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
2bb10 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
2bb20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
2bb30 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
2bb40 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
2bb50 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
2bb60 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
2bb70 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
2bb80 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
2bb90 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
2bba0 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
2bbb0 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
2bbc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bbd0 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
2bbe0 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
2bbf0 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
2bc00 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
2bc10 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
2bc20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bc30 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
2bc40 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
2bc50 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
2bc60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bc70 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
2bc80 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
2bc90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2bca0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
2bcb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bcc0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
2bcd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bce0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
2bcf0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
2bd00 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
2bd10 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2bd20 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
2bd30 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
2bd40 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
2bd50 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2bd60 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
2bd70 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2bd80 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
2bd90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bda0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2bdb0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
2bdc0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
2bdd0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
2bde0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
2bdf0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
2be00 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
2be10 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
2be20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2be30 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
2be40 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2be50 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
2be60 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
2be70 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
2be80 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
2be90 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
2bea0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
2beb0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
2bec0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
2bed0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
2bee0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
2bef0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
2bf00 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
2bf10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2bf20 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
2bf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf40 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
2bf50 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
2bf60 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
2bf70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2bf80 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
2bf90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
2bfa0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
2bfb0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
2bfc0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
2bfd0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
2bfe0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
2bff0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
2c000 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
2c010 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
2c020 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
2c030 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
2c040 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
2c050 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
2c060 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
2c070 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
2c080 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
2c090 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
2c0a0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
2c0b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
2c0c0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
2c0d0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
2c0e0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
2c0f0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
2c100 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
2c110 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
2c120 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
2c130 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
2c140 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
2c150 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
2c160 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
2c170 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
2c180 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2c190 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
2c1a0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
2c1b0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
2c1c0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
2c1d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2c1e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
2c1f0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
2c200 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
2c210 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
2c220 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2c230 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
2c240 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
2c250 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
2c260 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
2c270 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
2c280 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
2c290 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
2c2a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
2c2b0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
2c2c0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
2c2d0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
2c2e0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
2c2f0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
2c300 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
2c310 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
2c320 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
2c330 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
2c340 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
2c350 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
2c360 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
2c370 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
2c380 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
2c390 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
2c3a0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
2c3b0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
2c3c0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
2c3d0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
2c3e0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
2c3f0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
2c400 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
2c410 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
2c420 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
2c430 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
2c440 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
2c450 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
2c460 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
2c470 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
2c480 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
2c490 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
2c4a0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2c4b0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
2c4c0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
2c4d0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
2c4e0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
2c4f0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
2c500 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
2c510 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
2c520 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
2c530 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
2c540 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
2c550 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
2c560 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
2c570 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
2c580 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
2c590 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
2c5a0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
2c5b0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
2c5c0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
2c5d0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
2c5e0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
2c5f0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
2c600 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
2c610 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
2c620 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2c630 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
2c640 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
2c650 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
2c660 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
2c670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c680 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
2c690 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
2c6a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
2c6b0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
2c6c0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
2c6d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2c6e0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2c6f0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
2c700 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
2c710 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
2c720 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
2c730 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2c740 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
2c750 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
2c760 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
2c770 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
2c780 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
2c790 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2c7a0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
2c7b0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
2c7c0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
2c7d0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2c7e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c7f0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2c800 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2c810 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c820 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
2c830 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
2c840 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
2c850 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
2c860 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c870 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c880 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c890 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c8a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2c8b0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2c8c0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
2c8d0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
2c8e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c8f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2c900 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
2c910 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2c920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c930 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c940 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2c950 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2c960 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2c970 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2c980 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2c990 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2c9a0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2c9b0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2c9c0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2c9d0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2c9e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c9f0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2ca00 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2ca10 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2ca20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2ca30 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2ca40 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2ca50 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2ca60 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2ca70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2ca80 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2ca90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2caa0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2cab0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2cac0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2cad0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2cae0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2caf0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2cb00 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2cb10 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2cb20 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2cb30 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2cb40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2cb50 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2cb60 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2cb70 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2cb80 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2cb90 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2cba0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2cbb0 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2cbc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2cbd0 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2cbe0 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2cbf0 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2cc00 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2cc10 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2cc20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2cc30 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2cc40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2cc50 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2cc60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2cc70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2cc80 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2cc90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2cca0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2ccb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ccc0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2ccd0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2cce0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2ccf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2cd00 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2cd10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2cd20 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2cd30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2cd40 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2cd50 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2cd60 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2cd70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2cd80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2cd90 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2cda0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2cdb0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2cdc0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2cdd0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2cde0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2cdf0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2ce00 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2ce10 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2ce20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2ce30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2ce40 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2ce50 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2ce60 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2ce70 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2ce80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2ce90 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2cea0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2ceb0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2cec0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2ced0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2cee0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2cef0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2cf00 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2cf10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2cf20 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2cf30 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2cf40 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2cf50 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cf60 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2cf70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2cf80 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2cf90 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2cfa0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2cfb0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2cfc0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2cfd0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2cfe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cff0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2d000 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2d010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d020 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2d030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d040 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2d050 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2d060 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2d070 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2d080 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2d090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d0a0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2d0b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2d0c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2d0d0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2d0e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2d0f0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2d100 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2d110 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2d120 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2d130 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2d140 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2d150 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2d160 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2d170 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2d180 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2d190 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2d1a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2d1b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2d1c0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2d1d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2d1e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2d1f0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2d200 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2d210 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2d220 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2d230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2d240 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2d250 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2d260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d270 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a  Prepare Flags.**
2d280 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2d290 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2d2a0 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61  us flags that ca
2d2b0 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f  n be passed into
2d2c0 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20  .** "prepFlags" 
2d2d0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2d2e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d2f0 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  e_v3()] and.** [
2d300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d310 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63  6_v3()] interfac
2d320 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c  es..**.** New fl
2d330 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ags may be added
2d340 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2d350 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2d360 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2d370 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2d380 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74  RSISTENT]] ^(<dt
2d390 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2d3a0 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a  PERSISTENT</dt>.
2d3b0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2d3c0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2d3d0 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68  TENT flag is a h
2d3e0 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79  int to the query
2d3f0 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74   planner.** that
2d400 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d410 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2d420 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c  retained for a l
2d430 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20  ong time and.** 
2d440 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20  probably reused 
2d450 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57  many times.)^ ^W
2d460 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67  ithout this flag
2d470 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2d480 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20  re_v3()].** and 
2d490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d4a0 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20  16_v3()] assume 
2d4b0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2d4c0 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2d4d0 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73   .** be used jus
2d4e0 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2d4f0 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2d500 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2d510 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d520 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2d530 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20  elatively soon. 
2d540 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  The current impl
2d550 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a  ementation acts.
2d560 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ** on this hint 
2d570 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20  by avoiding the 
2d580 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64  use of [lookasid
2d590 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20  e memory] so as 
2d5a0 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74  not to.** deplet
2d5b0 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74  e the limited st
2d5c0 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ore of lookaside
2d5d0 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20   memory. Future 
2d5e0 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53  versions of.** S
2d5f0 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e  QLite may act on
2d600 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65   this hint diffe
2d610 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  rently..**.** [[
2d620 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d630 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53  ORMALIZE]] <dt>S
2d640 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d650 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  RMALIZE</dt>.** 
2d660 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2d670 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2d680 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70   flag is a no-op
2d690 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64  . This flag used
2d6a0 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72  .** to be requir
2d6b0 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61  ed for any prepa
2d6c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68  red statement th
2d6d0 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65  at wanted to use
2d6e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2d6f0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2d700 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48  )] interface.  H
2d710 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b  owever, the.** [
2d720 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2d730 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66  ed_sql()] interf
2d740 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c  ace is now avail
2d750 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70  able to all.** p
2d760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d770 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ts, regardless o
2d780 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2d790 20 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a   they use this.*
2d7a0 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  * flag..**.** [[
2d7b0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d7c0 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c  O_VTAB]] <dt>SQL
2d7d0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56  ITE_PREPARE_NO_V
2d7e0 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TAB</dt>.** <dd>
2d7f0 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2d800 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20  RE_NO_VTAB flag 
2d810 63 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63  causes the SQL c
2d820 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65  ompiler.** to re
2d830 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65  turn an error (e
2d840 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45  rror code SQLITE
2d850 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73  _ERROR) if the s
2d860 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a  tatement uses.**
2d870 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62   any virtual tab
2d880 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  les..** </dl>.*/
2d890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d8a0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2d8b0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2d8c0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
2d8d0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2d8e0 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALIZE           
2d8f0 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
2d900 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2d910 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NO_VTAB         
2d920 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a          0x04../*
2d930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d940 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2d950 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2d960 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2d970 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2d980 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d990 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2d9a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d9b0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2d9c0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2d9d0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2d9e0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2d9f0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2da00 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2da10 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2da20 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68  nes.  Or, in oth
2da30 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20  er words, these 
2da40 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2da50 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72  constructors for
2da60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2da70 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
2da80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66  ..**.** The pref
2da90 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f  erred routine to
2daa0 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33   use is [sqlite3
2dab0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20  _prepare_v2()]. 
2dac0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2dad0 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65  _prepare()] inte
2dae0 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20  rface is legacy 
2daf0 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76  and should be av
2db00 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  oided..** [sqlit
2db10 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2db20 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70   has an extra "p
2db30 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e  repFlags" option
2db40 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a   that is used.**
2db50 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72   for special pur
2db60 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  poses..**.** The
2db70 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d   use of the UTF-
2db80 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  8 interfaces is 
2db90 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51  preferred, as SQ
2dba0 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a  Lite currently.*
2dbb0 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69  * does all parsi
2dbc0 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20  ng using UTF-8. 
2dbd0 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2dbe0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
2dbf0 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76  ded.** as a conv
2dc00 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54  enience.  The UT
2dc10 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2dc20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69  work by converti
2dc30 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  ng the.** input 
2dc40 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c  text into UTF-8,
2dc50 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74   then invoking t
2dc60 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2dc70 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2dc80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2dc90 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2dca0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2dcb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2dcc0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2dcd0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2dce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2dcf0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2dd00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2dd10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2dd20 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2dd30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dd40 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2dd50 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2dd60 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2dd70 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2dd80 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2dd90 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2dda0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2ddb0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2ddc0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2ddd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73  te3_prepare(), s
2dde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ddf0 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2de00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2de10 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
2de20 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
2de30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2de40 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2de50 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2de60 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2de70 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46  e16_v3() use UTF
2de80 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2de90 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2dea0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2deb0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2dec0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2ded0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2dee0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2def0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2df00 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2df10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2df20 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2df30 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2df40 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2df50 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2df60 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2df70 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2df80 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2df90 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2dfa0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2dfb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2dfc0 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2dfd0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2dfe0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2dff0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2e000 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2e010 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e020 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2e030 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2e040 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2e050 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2e060 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2e070 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2e080 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2e090 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2e0a0 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2e0b0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2e0c0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2e0d0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2e0e0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2e0f0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2e100 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2e110 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2e120 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2e130 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2e140 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2e150 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2e160 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2e170 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2e180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e190 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2e1a0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2e1b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2e1c0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2e1d0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2e1e0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2e1f0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2e200 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2e210 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2e220 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2e230 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2e240 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2e250 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2e260 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2e270 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2e280 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2e290 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2e2a0 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2e2b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2e2c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2e2d0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2e2e0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2e2f0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2e300 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2e310 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2e320 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2e330 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2e340 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2e350 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2e360 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2e370 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2e380 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2e390 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2e3a0 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c  repare_v2(), sql
2e3b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2e3c0 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2e3d0 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2e3e0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2e3f0 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61  e16_v3() interfa
2e400 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e  ces are recommen
2e410 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2e420 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65  programs..** The
2e430 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2e440 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s (sqlite3_prepa
2e450 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
2e460 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a  _prepare16()).**
2e470 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
2e480 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2e490 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2e4a0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2e4b0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2e4c0 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
2e4d0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2e4e0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2e4f0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2e500 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2e510 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2e520 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2e530 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2e540 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2e550 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2e560 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2e570 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2e580 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2e590 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2e5a0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2e5b0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2e5c0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2e5d0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2e5e0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2e5f0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2e600 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2e610 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2e620 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2e630 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2e640 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2e650 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2e660 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2e670 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2e680 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2e690 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2e6a0 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2e6b0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e6c0 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2e6d0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2e6e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2e6f0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2e700 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2e710 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2e720 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2e730 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2e740 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2e750 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2e760 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2e770 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2e780 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2e790 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2e7a0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2e7b0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2e7c0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2e7d0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2e7e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2e7f0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2e800 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2e810 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e820 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2e830 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2e840 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2e850 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2e860 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2e870 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2e880 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2e890 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2e8a0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2e8b0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2e8c0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2e8d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2e8e0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2e8f0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2e900 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2e910 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2e920 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2e930 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2e940 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2e950 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2e960 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2e970 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2e980 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2e990 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2e9a0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2e9b0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2e9c0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2e9d0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2e9e0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2e9f0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2ea00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ea10 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2ea20 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2ea30 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2ea40 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2ea50 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2ea60 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2ea70 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2ea80 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2ea90 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2eaa0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2eab0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2eac0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2ead0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2eae0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2eaf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2eb00 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2eb10 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2eb20 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2eb30 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2eb40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2eb50 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2eb60 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
2eb70 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2eb80 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2eb90 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2eba0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2ebb0 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2ebc0 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2ebd0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2ebe0 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2ebf0 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2ec00 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2ec10 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2ec20 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2ec30 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2ec40 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2ec50 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2ec60 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2ec70 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2ec80 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2ec90 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2eca0 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2ecb0 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2ecc0 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  rameter..*/.SQLI
2ecd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ece0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2ecf0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ed00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ed10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ed20 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ed30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ed40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2ed50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ed60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ed70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ed80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2ed90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2eda0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2edb0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2edc0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2edd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2ede0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2edf0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ee00 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2ee10 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2ee20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ee30 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2ee40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ee50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ee60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ee70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2ee80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ee90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2eea0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2eeb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2eec0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2eed0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2eee0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2eef0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ef00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ef10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2ef20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2ef30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2ef40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2ef50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2ef60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2ef70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ef80 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20  3_prepare_v3(.  
2ef90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2efa0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2efb0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2efc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2efd0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2efe0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2eff0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2f000 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2f010 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2f020 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2f030 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2f040 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2f050 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2f060 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2f070 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2f080 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2f090 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2f0a0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2f0b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2f0c0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2f0d0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2f0e0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2f0f0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2f100 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2f120 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2f130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2f140 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2f150 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2f160 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2f170 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2f180 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2f190 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2f1a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2f1b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2f1c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2f1d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2f1e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2f1f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2f200 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2f210 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2f220 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2f230 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2f240 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2f250 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2f270 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2f280 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2f290 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2f2a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2f2b0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2f2c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2f2d0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2f2e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2f2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f300 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2f310 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2f320 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2f330 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2f340 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2f350 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f360 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2f370 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2f380 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2f390 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2f3a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2f3b0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2f3c0 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74  re16_v3(.  sqlit
2f3d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2f3e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2f3f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2f400 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2f410 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2f420 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2f430 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2f440 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2f450 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2f460 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2f470 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2f480 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2f490 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2f4a0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2f4b0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2f4c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2f4d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2f4e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2f4f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2f500 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2f510 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2f520 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2f530 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2f540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2f550 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2f560 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2f570 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f580 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f590 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2f5a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f5b0 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2f5c0 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2f5d0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2f5e0 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2f5f0 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2f600 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2f610 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
2f620 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2f630 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2f640 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
2f650 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
2f660 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2f670 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20  are16_v3()]..** 
2f680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2f690 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2f6a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f6b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2f6c0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2f6d0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2f6e0 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2f6f0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2f700 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2f710 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2f720 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2f730 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71  e3_normalized_sq
2f740 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2f750 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f760 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73   to a UTF-8.** s
2f770 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2f780 20 74 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20   the normalized 
2f790 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70  SQL text of prep
2f7a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2f7b0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74  .  The.** semant
2f7c0 69 63 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d  ics used to norm
2f7d0 61 6c 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74  alize a SQL stat
2f7e0 65 6d 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63  ement are unspec
2f7f0 69 66 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63  ified and subjec
2f800 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20  t.** to change. 
2f810 20 41 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c   At a minimum, l
2f820 69 74 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69  iteral values wi
2f830 6c 6c 20 62 65 20 72 65 70 6c 61 63 65 64 20 77  ll be replaced w
2f840 69 74 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20  ith suitable.** 
2f850 70 6c 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a  placeholders..**
2f860 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2f870 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64  e, if a prepared
2f880 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72   statement is cr
2f890 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  eated using the 
2f8a0 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c  SQL.** text "SEL
2f8b0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61  ECT $abc,:xyz" a
2f8c0 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  nd if parameter 
2f8d0 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f  $abc is bound to
2f8e0 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a   integer 2345.**
2f8f0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a   and parameter :
2f900 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20  xyz is unbound, 
2f910 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c  then sqlite3_sql
2f920 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
2f930 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
2f940 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24  tring, "SELECT $
2f950 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71  abc,:xyz" but sq
2f960 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f970 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  ql().** will ret
2f980 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35  urn "SELECT 2345
2f990 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ,NULL".)^.**.** 
2f9a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2f9b0 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65  anded_sql() inte
2f9c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
2f9d0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
2f9e0 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  nt memory.** is 
2f9f0 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c  available to hol
2fa00 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72  d the result, or
2fa10 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77   if the result w
2fa20 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2fa30 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  ** the maximum s
2fa40 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74  tring length det
2fa50 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
2fa60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2fa70 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  GTH]..**.** ^The
2fa80 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
2fa90 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
2faa0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c  le-time option l
2fab0 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2fac0 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d  f.** bound param
2fad0 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e  eter expansions.
2fae0 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
2faf0 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  MIT_TRACE] compi
2fb00 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
2fb10 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33  n causes sqlite3
2fb20 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2fb30 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  to always return
2fb40 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2fb50 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
2fb60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2fb70 6c 28 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  l(P) and sqlite3
2fb80 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2fb90 50 29 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65  P).** are manage
2fba0 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20  d by SQLite and 
2fbb0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
2fbc0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2fbd0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2fbe0 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
2fbf0 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72  zed..** ^The str
2fc00 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2fc10 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2fc20 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20  _sql(P), on the 
2fc30 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69  other hand,.** i
2fc40 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2fc50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2fc60 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66  )] and must be f
2fc70 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69  ree by the appli
2fc80 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73  cation.** by pas
2fc90 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
2fca0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a  te3_free()]..*/.
2fcb0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2fcc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2fcd0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2fce0 2a 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f  *pStmt);.SQLITE_
2fcf0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
2fd00 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2fd10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fd20 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  mt);.SQLITE_API 
2fd30 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2fd40 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73  te3_normalized_s
2fd50 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2fd60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2fd70 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2fd80 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
2fd90 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
2fda0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
2fdb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2fdc0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2fdd0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2fde0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2fdf0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2fe00 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2fe10 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2fe20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fe30 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2fe40 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2fe50 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2fe60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2fe70 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2fe80 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2fe90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2fea0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2feb0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2fec0 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2fed0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2fee0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2fef0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2ff00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2ff10 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2ff20 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2ff30 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2ff40 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2ff50 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2ff60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2ff70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2ff80 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2ff90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2ffa0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2ffb0 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2ffc0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2ffd0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2ffe0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2fff0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
30000 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
30010 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
30020 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
30030 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
30040 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
30050 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
30060 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
30070 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
30080 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
30090 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
300a0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
300b0 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
300c0 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
300d0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
300e0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
300f0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
30100 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
30110 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
30120 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
30130 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
30140 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
30150 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
30160 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
30170 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
30180 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
30190 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
301a0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
301b0 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
301c0 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
301d0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
301e0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
301f0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
30200 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
30210 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
30220 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
30230 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
30240 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
30250 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
30260 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
30270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30280 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
30290 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
302a0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
302b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
302c0 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
302d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
302e0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69  tmt_readonly() i
302f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30300 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e   true for [BEGIN
30310 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49  ] since.** [BEGI
30320 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69  N] merely sets i
30330 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62  nternal flags, b
30340 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45  ut the [BEGIN|BE
30350 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61  GIN IMMEDIATE] a
30360 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47  nd.** [BEGIN|BEG
30370 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f  IN EXCLUSIVE] co
30380 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20  mmands do touch 
30390 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
303a0 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   so.** sqlite3_s
303b0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72  tmt_readonly() r
303c0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72  eturns false for
303d0 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e   those commands.
303e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
303f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
30400 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
30410 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
30420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30430 51 75 65 72 79 20 54 68 65 20 45 58 50 4c 41 49  Query The EXPLAI
30440 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20 41 20  N Setting For A 
30450 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30460 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
30470 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
30490 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53 29 20  mt_isexplain(S) 
304a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
304b0 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  s 1 if the.** pr
304c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
304d0 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49 4e   S is an EXPLAIN
304e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 20 32   statement, or 2
304f0 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61 74 65   if the.** state
30500 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50  ment S is an EXP
30510 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 2e  LAIN QUERY PLAN.
30520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30530 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28  _stmt_isexplain(
30540 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
30550 75 72 6e 73 20 30 20 69 66 20 53 20 69 73 0a 2a  urns 0 if S is.*
30560 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 73 74  * an ordinary st
30570 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e 55 4c  atement or a NUL
30580 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51  L pointer..*/.SQ
30590 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
305a0 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c  ite3_stmt_isexpl
305b0 61 69 6e 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ain(sqlite3_stmt
305c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
305d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
305e0 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
305f0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
30600 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
30610 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30620 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
30630 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
30640 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
30650 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
30660 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
30670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30680 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
30690 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
306a0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
306b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
306c0 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
306d0 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
306e0 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
306f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
30700 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
30710 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
30720 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
30730 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30740 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
30750 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
30760 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30770 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
30780 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
30790 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
307a0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
307b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
307c0 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
307d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
307e0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
307f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30800 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
30810 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
30820 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
30830 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
30840 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
30850 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
30860 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
30870 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
30880 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30890 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
308a0 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
308b0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
308c0 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
308d0 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
308e0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
308f0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
30900 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
30910 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
30920 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
30930 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
30940 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
30950 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
30960 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
30970 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
30980 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
30990 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
309a0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
309b0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
309c0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
309d0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
309e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
309f0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
30a00 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
30a10 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
30a20 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
30a30 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
30a40 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
30a50 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
30a60 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
30a70 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
30a80 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
30a90 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
30aa0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
30ab0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
30ac0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
30ad0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
30ae0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
30af0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
30b00 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
30b10 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
30b20 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
30b30 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
30b40 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
30b50 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
30b60 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
30b70 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
30b80 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
30b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
30ba0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
30bb0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
30bc0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
30bd0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
30be0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30bf0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
30c00 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
30c10 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
30c20 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
30c30 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
30c40 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
30c50 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
30c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
30c70 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
30c80 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
30c90 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
30ca0 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
30cb0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
30cc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30cd0 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
30ce0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30cf0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
30d00 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
30d10 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
30d20 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
30d30 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
30d40 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
30d50 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
30d60 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
30d70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
30d80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
30d90 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
30da0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
30db0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
30dc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
30dd0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
30de0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
30df0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
30e00 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
30e10 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
30e20 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
30e30 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
30e40 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
30e50 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
30e60 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
30e70 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
30e80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
30e90 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
30ea0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
30eb0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
30ec0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
30ed0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
30ee0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
30ef0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
30f00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
30f10 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
30f20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
30f30 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
30f40 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
30f50 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
30f60 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
30f70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
30f80 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
30f90 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
30fa0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
30fb0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
30fc0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
30fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
30fe0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
30ff0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
31000 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
31010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
31020 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
31030 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
31040 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
31050 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
31060 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
31070 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31080 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
31090 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
310a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
310b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
310c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
310d0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
310e0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
310f0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
31100 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
31110 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
31120 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74  used as argument
31130 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
31140 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
31150 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  , [sqlite3_bind_
31160 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  value()], and.**
31170 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31180 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  dup()]..** The [
31190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
311a0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
311b0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
311c0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
311d0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
311e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
311f0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
31200 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
31210 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
31220 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
31230 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
31240 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
31250 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
31260 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
31270 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
31280 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
31290 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
312a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
312b0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
312c0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
312d0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
312e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
312f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
31300 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
31310 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
31320 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
31330 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
31350 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
31360 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
31370 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
31380 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
31390 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
313a0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
313b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
313c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
313d0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
313e0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
313f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
31400 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
31410 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
31420 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
31430 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
31440 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
31450 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
31460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
31470 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
31480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31490 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
314a0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
314b0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
314c0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
314d0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
314e0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
314f0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
31500 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
31510 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
31520 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
31530 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
31540 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31550 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
31560 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
31570 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
31580 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31590 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
315a0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
315b0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
315c0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
315d0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
315e0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
315f0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
31600 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
31610 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
31620 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
31630 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
31640 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
31650 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
31660 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
31670 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
31680 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
31690 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
316a0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
316b0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
316c0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
316d0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
316e0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
316f0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
31700 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
31710 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
31720 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
31730 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
31740 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
31750 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
31760 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
31770 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
31780 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
31790 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
317a0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
317b0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
317c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
317d0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
317e0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
317f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
31800 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
31810 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
31820 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
31830 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
31840 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
31850 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
31860 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
31870 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
31880 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
31890 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
318a0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
318b0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
318c0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
318d0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
318e0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
318f0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
31900 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
31910 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
31920 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
31930 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
31940 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
31950 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
31960 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
31970 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
31980 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
31990 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
319a0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
319b0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
319c0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
319d0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
319e0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
319f0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
31a00 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
31a10 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
31a20 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
31a30 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
31a40 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
31a50 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
31a60 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
31a70 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
31a80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
31a90 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
31aa0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31ab0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
31ac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31ad0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
31ae0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
31af0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
31b00 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
31b10 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
31b20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
31b30 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
31b40 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
31b50 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
31b60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
31b70 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
31b80 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
31b90 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
31ba0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
31bb0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
31bc0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
31bd0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
31be0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
31bf0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
31c00 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
31c10 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
31c20 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
31c30 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
31c40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31c50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
31c60 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
31c70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
31c80 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
31c90 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
31ca0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
31cb0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
31cc0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
31cd0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
31ce0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
31cf0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
31d00 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31d10 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
31d20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
31d30 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
31d40 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
31d50 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
31d60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31d70 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
31d80 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
31d90 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
31da0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
31db0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
31dc0 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
31dd0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
31de0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
31df0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
31e00 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
31e10 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
31e20 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
31e30 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
31e40 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
31e50 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
31e60 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
31e70 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
31e80 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
31e90 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
31ea0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
31eb0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
31ec0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
31ed0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
31ee0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
31ef0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
31f00 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
31f10 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
31f20 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
31f30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31f40 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
31f50 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
31f60 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
31f70 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
31f80 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
31f90 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
31fa0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
31fb0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
31fc0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
31fd0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
31fe0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
31ff0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
32000 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
32010 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
32020 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
32030 20 74 68 65 20 62 69 6e 64 20 41 50 49 20 66 61   the bind API fa
32040 69 6c 73 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74  ils,.** except t
32050 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
32060 20 6e 6f 74 20 63 61 6c 6c 65 64 20 69 66 20 74   not called if t
32070 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
32080 65 72 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20  er is a NULL.** 
32090 70 6f 69 6e 74 65 72 20 6f 72 20 74 68 65 20 66  pointer or the f
320a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
320b0 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 20  is negative..** 
320c0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
320d0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
320e0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
320f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
32100 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
32110 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
32120 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
32130 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
32140 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
32150 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
32160 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
32170 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
32180 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
32190 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
321a0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
321b0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
321c0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
321d0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
321e0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
321f0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
32200 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
32210 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
32220 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
32230 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
32240 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
32250 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
32260 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
32270 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
32280 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
32290 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
322a0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
322b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
322c0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
322d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
322e0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
322f0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
32300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
32310 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
32320 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
32330 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
32340 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
32350 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
32360 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
32370 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
32380 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
32390 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
323a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
323b0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
323c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
323d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
323e0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
323f0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
32400 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
32410 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
32420 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
32430 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
32440 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
32450 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
32460 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
32470 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
32480 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
32490 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
324a0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
324b0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
324c0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
324d0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
324e0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
324f0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
32500 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
32510 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
32520 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
32530 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
32540 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
32550 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
32560 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
32570 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
32580 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
32590 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
325a0 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
325b0 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
325c0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
325d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
325e0 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
325f0 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
32600 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
32610 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32620 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
32630 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
32640 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
32650 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
32660 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
32670 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
32680 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
32690 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
326a0 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
326b0 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
326c0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
326d0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
326e0 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
326f0 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
32700 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
32710 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
32720 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
32730 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
32740 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
32750 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
32760 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
32770 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
32780 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
32790 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
327a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
327b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
327c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
327d0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
327e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
327f0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
32800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
32810 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
32820 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
32830 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
32840 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
32850 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
32860 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
32870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
32880 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
32890 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
328a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
328b0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
328c0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
328d0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
328e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
328f0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
32900 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
32910 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
32920 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
32930 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
32940 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
32950 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
32960 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
32970 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
32980 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
32990 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
329a0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
329b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
329c0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
329d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
329e0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
329f0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
32a00 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
32a10 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
32a20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
32a30 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
32a40 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
32a50 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
32a60 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
32a70 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
32a80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
32a90 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
32aa0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
32ab0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
32ac0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
32ad0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
32ae0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
32af0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
32b00 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
32b10 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
32b20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
32b30 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
32b40 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
32b50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32b60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
32b70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
32b80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
32b90 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
32ba0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
32bb0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
32bc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32bd0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
32be0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32bf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32c00 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
32c10 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
32c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32c30 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
32c40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
32c50 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
32c60 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
32c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32c80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32c90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
32cb0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
32cc0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
32cd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32ce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
32cf0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
32d00 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
32d10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32d20 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
32d30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32d40 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
32d50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32d60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
32d70 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
32d80 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
32d90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
32da0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
32db0 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
32dc0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
32dd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32de0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32df0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
32e00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32e10 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
32e20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32e30 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
32e40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
32e50 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
32e60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
32e70 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
32e80 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
32e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32ea0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
32eb0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
32ec0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
32ed0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32ee0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
32ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32f00 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
32f10 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32f20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32f30 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c  bind_pointer(sql
32f40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32f50 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68   void*, const ch
32f60 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  ar*,void(*)(void
32f70 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
32f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32f90 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
32fa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
32fb0 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t n);.SQLITE_API
32fc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
32fd0 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
32fe0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32ff0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
33000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33010 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
33020 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
33030 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
33040 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
33050 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
33060 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
33070 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
33080 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
33090 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
330a0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
330b0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
330c0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
330d0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
330e0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
330f0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
33100 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
33110 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
33120 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
33130 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
33140 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
33150 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
33160 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
33170 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
33180 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
33190 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
331a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
331b0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
331c0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
331d0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
331e0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
331f0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
33200 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
33210 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
33220 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
33230 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
33240 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
33250 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
33260 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
33270 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
33280 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
33290 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
332a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
332b0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
332c0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
332d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
332e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
332f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
33310 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
33320 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
33330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
33340 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
33350 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
33360 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33380 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
33390 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
333a0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
333b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
333c0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
333d0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
333e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
333f0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
33400 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
33410 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
33420 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
33430 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
33440 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
33450 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
33460 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
33470 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
33480 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
33490 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
334a0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
334b0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
334c0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
334d0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
334e0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
334f0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
33500 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
33510 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
33520 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
33530 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
33540 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
33550 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
33560 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
33570 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
33580 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
33590 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
335a0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
335b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
335c0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
335d0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
335e0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
335f0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
33600 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
33610 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
33620 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
33630 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
33640 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
33650 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
33660 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
33670 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
33680 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
33690 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
336a0 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  e16()],.** [sqli
336b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
336c0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
336d0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
336e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
336f0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
33700 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
33710 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
33720 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
33730 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
33740 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
33750 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
33760 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
33770 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
33780 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
33790 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
337a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
337b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
337c0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
337d0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
337e0 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
337f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33800 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
33810 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
33820 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
33830 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
33840 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
33850 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
33860 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
33870 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
33880 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
33890 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
338a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
338b0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
338c0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
338d0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
338e0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
338f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
33900 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
33910 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
33920 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
33930 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
33940 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
33950 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
33960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33970 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  6_v2()] or.** [s
33980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33990 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
339a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
339b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
339c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
339d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
339e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
339f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
33a00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
33a10 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  name()]..*/.SQLI
33a20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
33a30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
33a40 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
33a50 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
33a60 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
33a70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
33a80 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
33a90 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
33aa0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
33ab0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33ac0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
33ad0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
33ae0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
33af0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
33b00 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
33b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33b20 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
33b30 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
33b40 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
33b50 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
33b60 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
33b70 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
33b80 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
33b90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33ba0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
33bb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
33bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33bd0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
33be0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
33bf0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33c00 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33c10 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
33c20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33c30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33c40 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
33c50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
33c60 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69  tement]. ^If thi
33c70 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
33c80 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  s 0, that means 
33c90 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
33ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74  d statement] ret
33cb0 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f  urns no data (fo
33cc0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
33cd0 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65  DATE])..** ^Howe
33ce0 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73  ver, just becaus
33cf0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  e this routine r
33d00 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76  eturns a positiv
33d10 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f  e number does no
33d20 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f  t.** mean that o
33d30 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ne or more rows 
33d40 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20  of data will be 
33d50 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45  returned.  ^A SE
33d60 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a  LECT statement.*
33d70 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61  * will always ha
33d80 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71  ve a positive sq
33d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
33da0 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69  nt() but dependi
33db0 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45  ng on the.** WHE
33dc0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
33dd0 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61  aints and the ta
33de0 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20  ble content, it 
33df0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20  might return no 
33e00 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rows..**.** See 
33e10 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
33e20 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
33e30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
33e50 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
33e60 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
33e70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
33e80 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
33e90 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
33ea0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
33ec0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
33ed0 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
33ee0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
33ef0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
33f00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
33f10 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
33f20 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
33f30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
33f40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
33f50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
33f60 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
33f70 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
33f80 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
33f90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
33fa0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
33fb0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
33fc0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
33fd0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
33fe0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
33ff0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
34000 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
34010 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
34020 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
34030 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
34040 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
34050 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
34060 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
34070 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
34080 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
34090 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
340a0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
340b0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
340c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
340d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
340e0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
340f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34100 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
34110 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
34120 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
34130 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
34140 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
34150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
34160 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
34170 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
34180 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
34190 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
341a0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
341b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
341c0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
341d0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
341e0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
341f0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
34200 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
34210 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
34220 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
34230 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
34240 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
34250 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
34260 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
34270 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34280 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
34290 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
342a0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
342b0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
342c0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
342d0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
342e0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
342f0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
34300 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
34310 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
34320 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
34330 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
34340 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
34350 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
34360 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
34370 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34380 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
34390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
343a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
343b0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
343c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
343d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
343e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
343f0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
34400 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
34410 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
34420 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
34430 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34440 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
34450 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
34460 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
34470 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
34480 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
34490 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
344a0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
344b0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
344c0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
344d0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
344e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
344f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
34500 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
34510 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
34520 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
34530 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
34540 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
34550 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
34560 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
34570 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
34580 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
34590 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
345a0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
345b0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
345c0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
345d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
345e0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
345f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
34600 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
34610 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34620 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
34630 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
34640 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34650 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
34660 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
34670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
34680 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
34690 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
346a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
346b0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
346c0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
346d0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
346e0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
346f0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
34700 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
34710 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
34720 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
34730 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
34740 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
34750 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
34760 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
34770 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
34780 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
34790 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
347a0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
347b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
347c0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
347d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
347e0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
347f0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
34800 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
34810 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
34820 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
34830 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
34840 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
34850 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
34860 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
34870 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
34880 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
34890 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
348a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
348b0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
348c0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
348d0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
348e0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
348f0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
34900 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
34910 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
34920 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
34930 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
34940 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
34950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
34960 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
34970 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
34980 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
34990 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
349a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
349b0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
349c0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
349d0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
349e0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
349f0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
34a00 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
34a10 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
34a20 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
34a30 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
34a40 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
34a50 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
34a60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
34a70 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
34a80 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
34a90 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
34aa0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
34ab0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
34ac0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
34ad0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
34ae0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
34af0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
34b00 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
34b10 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
34b20 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34b30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
34b40 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
34b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34b60 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
34b70 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
34b80 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34b90 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
34ba0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
34bb0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
34bc0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
34bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34be0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
34bf0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
34c00 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
34c10 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
34c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34c30 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
34c40 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
34c50 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
34c60 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34c70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
34c80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
34c90 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34ca0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
34cb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
34cc0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
34cd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
34cf0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
34d00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
34d10 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34d20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
34d30 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
34d40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
34d50 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
34d60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34d70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
34d80 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
34d90 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
34da0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
34db0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34dc0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
34dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34de0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34df0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34e00 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
34e10 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
34e20 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
34e30 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
34e40 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
34e50 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
34e60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34e70 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
34e80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34e90 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
34ea0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
34eb0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
34ec0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
34ed0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
34ee0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
34ef0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
34f00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
34f10 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
34f20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
34f30 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
34f40 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
34f50 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
34f60 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
34f70 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
34f80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
34f90 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
34fa0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
34fb0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
34fc0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
34fd0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
34fe0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
34ff0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
35000 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
35010 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
35020 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
35030 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
35040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
35050 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
35060 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
35070 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
35080 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
35090 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
350a0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
350b0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
350c0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
350d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
350e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
350f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
35100 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
35110 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
35120 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
35130 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
35140 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
35150 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
35160 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
35170 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
35180 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
35190 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
351a0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
351b0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
351c0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
351d0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
351e0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
351f0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
35200 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
35210 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
35220 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
35230 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
35240 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
35250 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
35260 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
35270 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
35280 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
35290 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
352a0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
352b0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
352c0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
352d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
352e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
352f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
35300 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
35310 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
35320 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
35330 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
35340 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
35350 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
35360 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
35370 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
35380 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
35390 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
353a0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
353b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
353c0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
353d0 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
353e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
353f0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
35400 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
35410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35420 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
35430 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35440 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
35450 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
35460 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
35470 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
35480 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
35490 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
354a0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
354b0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
354c0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
354d0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
354e0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
354f0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
35500 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
35510 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
35520 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
35530 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
35540 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
35550 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
35560 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
35570 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
35580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
35590 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
355a0 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
355b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
355c0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
355d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
355e0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
355f0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
35600 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
35610 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
35620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
35630 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
35640 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
35650 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
35660 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
35670 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
35680 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
35690 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
356a0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
356b0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
356c0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
356d0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
356e0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
356f0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
35700 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
35710 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
35720 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
35730 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
35740 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
35750 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
35760 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
35770 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
35780 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
35790 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
357a0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
357b0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
357c0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
357d0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
357e0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
357f0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
35800 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
35810 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
35820 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
35830 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
35840 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
35850 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
35860 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
35870 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
35880 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
35890 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
358a0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
358b0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
358c0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
358d0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
358e0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
358f0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
35900 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
35910 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
35920 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
35930 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
35940 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
35950 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
35960 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
35970 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
35980 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
35990 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
359a0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
359b0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
359c0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
359d0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
359e0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
359f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
35a00 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
35a10 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
35a20 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
35a30 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
35a40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
35a50 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
35a60 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
35a70 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
35a80 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
35a90 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
35aa0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
35ab0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
35ac0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
35ad0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
35ae0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
35af0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
35b00 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
35b10 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
35b20 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
35b30 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
35b40 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
35b50 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
35b60 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
35b70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
35b80 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
35b90 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
35ba0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
35bb0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
35bc0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
35bd0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
35be0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
35bf0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
35c00 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
35c10 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
35c20 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
35c30 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
35c40 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
35c50 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
35c60 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
35c70 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
35c80 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
35c90 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
35ca0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
35cb0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
35cc0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
35cd0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
35ce0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
35cf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35d00 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
35d10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35d20 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
35d30 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
35d40 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
35d50 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
35d60 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
35d70 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
35d80 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
35d90 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
35da0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
35db0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
35dc0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
35dd0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
35de0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
35df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35e00 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
35e10 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
35e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
35e30 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
35e40 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
35e50 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
35e60 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
35e70 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
35e80 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
35e90 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
35ea0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
35eb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35ec0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
35ed0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
35ee0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
35ef0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
35f00 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
35f10 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
35f20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
35f30 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
35f40 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
35f50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
35f60 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
35f70 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
35f80 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
35f90 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
35fa0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
35fb0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
35fc0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
35fd0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
35fe0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
35ff0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
36000 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
36010 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
36020 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
36030 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
36040 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
36050 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
36060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
36070 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
36080 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
36090 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
360a0 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
360b0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
360c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
360d0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
360e0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
360f0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
36100 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
36110 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
36120 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
36130 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
36140 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
36150 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
36160 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
36170 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
36180 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
36190 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
361a0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
361b0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
361c0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
361d0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
361e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
361f0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
36200 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
36210 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
36220 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
36230 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
36240 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
36250 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
36260 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
36270 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
36280 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
36290 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
362a0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
362b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
362c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
362d0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
362e0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
362f0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
36300 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
36310 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36320 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
36330 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
36340 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
36350 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
36360 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
36370 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
36380 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
36390 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
363a0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
363b0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
363c0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
363d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
363e0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
363f0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
36400 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
36410 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
36420 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
36430 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
36440 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
36450 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
36460 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
36470 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
36480 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
36490 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
364a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
364b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
364c0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
364d0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
364e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
364f0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
36500 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
36510 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
36520 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
36530 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
36540 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
36550 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
36560 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
36570 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
36580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36590 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
365a0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
365b0 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
365c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
365d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
365e0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
365f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
36610 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
36620 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
36630 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
36640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36650 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
36660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36670 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
36680 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
36690 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
366a0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
366b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
366c0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
366d0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
366e0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
366f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
36700 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
36710 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36720 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
36730 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
36740 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
36750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36760 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36770 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
36780 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
36790 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
367a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
367b0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
367c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
367d0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
367e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
367f0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
36800 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
36810 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
36820 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
36830 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
36840 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
36850 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
36860 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
36870 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
36880 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
36890 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
368a0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
368b0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
368c0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
368d0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
368e0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
368f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
36900 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
36910 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36920 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
36930 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
36940 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
36950 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
36960 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
36970 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
36980 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
36990 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
369a0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
369b0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
369c0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
369d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
369e0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
369f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
36a00 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
36a10 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
36a20 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
36a30 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
36a40 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
36a50 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
36a60 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
36a70 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
36a80 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
36a90 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
36aa0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
36ab0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
36ac0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
36ad0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
36ae0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
36af0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
36b00 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
36b10 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
36b20 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
36b30 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
36b40 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
36b50 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
36b60 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
36b70 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
36b80 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
36b90 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
36ba0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
36bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
36bc0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
36bd0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
36be0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
36bf0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
36c00 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
36c10 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
36c20 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
36c30 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
36c40 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
36c50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
36c60 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
36c70 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
36c80 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
36c90 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
36ca0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36cb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c  te3_stmt.**.** <
36cc0 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a  b>Summary:</b>.*
36cd0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74  * <blockquote><t
36ce0 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65  able border=0 ce
36cf0 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c  llpadding=0 cell
36d00 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74  spacing=0>.** <t
36d10 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36d20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e  _column_blob</b>
36d30 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c  <td>&rarr;<td>BL
36d40 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  OB result.** <tr
36d50 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36d60 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62  column_double</b
36d70 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52  ><td>&rarr;<td>R
36d80 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EAL result.** <t
36d90 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36da0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c  _column_int</b><
36db0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d  td>&rarr;<td>32-
36dc0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
36dd0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
36de0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36df0 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61  int64</b><td>&ra
36e00 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e  rr;<td>64-bit IN
36e10 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
36e20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36e30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f  e3_column_text</
36e40 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36e50 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
36e60 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
36e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36e80 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61  ext16</b><td>&ra
36e90 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45  rr;<td>UTF-16 TE
36ea0 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
36eb0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36ec0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e  column_value</b>
36ed0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68  <td>&rarr;<td>Th
36ee0 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a  e result as an .
36ef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
36f00 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  e|unprotected sq
36f10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36f20 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ect..** <tr><td>
36f30 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
36f40 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74  <td>&nbsp;.** <t
36f50 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36f60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62  _column_bytes</b
36f70 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53  ><td>&rarr;<td>S
36f80 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a  ize of a BLOB.**
36f90 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 54   or a UTF-8 TEXT
36fa0 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73   result in bytes
36fb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
36fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36fd0 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70  tes16&nbsp;&nbsp
36fe0 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61  ;</b>.** <td>&ra
36ff0 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  rr;&nbsp;&nbsp;<
37000 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31  td>Size of UTF-1
37010 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74  6.** TEXT in byt
37020 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
37030 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
37040 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  type</b><td>&rar
37050 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a  r;<td>Default.**
37060 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
37070 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62   result.** </tab
37080 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  le></blockquote>
37090 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c  .**.** <b>Detail
370a0 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  s:</b>.**.** ^Th
370b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
370c0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
370d0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
370e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
370f0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
37100 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
37110 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
37120 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37130 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
37140 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
37150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
37160 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
37170 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
37180 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
37190 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
371a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
371b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
371c0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
371d0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
371e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
371f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
37200 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
37210 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
37220 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
37230 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
37240 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
37250 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
37260 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
37270 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
37280 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
37290 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
372a0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
372b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
372c0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
372d0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
372e0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
372f0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
37300 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
37310 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
37320 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
37330 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
37340 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
37350 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
37360 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
37370 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
37380 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
37390 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
373a0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
373b0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
373c0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
373d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
373e0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
373f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
37400 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
37410 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
37420 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
37430 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
37440 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
37450 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
37460 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
37470 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
37480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37490 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
374a0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
374b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
374c0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
374d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
374e0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
374f0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
37500 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
37510 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
37520 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
37530 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
37540 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
37550 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
37560 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
37570 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
37580 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
37590 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
375a0 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
375b0 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75  ces (_blob, _dou
375c0 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36  ble, _int, _int6
375d0 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74  4, _text, and _t
375e0 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72  ext16).** each r
375f0 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20  eturn the value 
37600 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
37610 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 63  mn in a specific
37620 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49   data format.  I
37630 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20  f.** the result 
37640 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e  column is not in
37650 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72  itially in the r
37660 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20  equested format 
37670 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
37680 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72 65   if the query re
37690 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
376a0 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 33   but the sqlite3
376b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
376c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75  nterface.** is u
376d0 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
376e0 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61  he value) then a
376f0 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  n automatic type
37700 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
37710 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
37720 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
37730 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
37740 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
37750 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
37760 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
37770 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
37780 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
37790 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
377a0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
377b0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
377c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
377d0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
377e0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
377f0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
37800 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
37810 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65  TE_NULL]..** The
37820 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
37830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37840 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 73  type() can be us
37850 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 69  ed to decide whi
37860 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72  ch.** of the fir
37870 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
37880 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20   should be used 
37890 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 63  to extract the c
378a0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20  olumn value..** 
378b0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
378c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
378d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
378e0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
378f0 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  f no.** automati
37900 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
37910 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
37920 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69   for the value i
37930 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a  n question.  .**
37940 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
37950 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65  nversion, the re
37960 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20  sult of calling 
37970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37980 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ype().** is unde
37990 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61  fined, though ha
379a0 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a  rmless.  Future.
379b0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
379c0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
379d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
379e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
379f0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
37a00 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
37a10 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
37a20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
37a30 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73  BLOB or a TEXT s
37a40 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  tring, then the 
37a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37a60 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  ytes().** or sql
37a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37a80 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 73  s16() interfaces
37a90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
37aa0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69  determine the si
37ab0 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c  ze.** of that BL
37ac0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
37ad0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
37ae0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
37af0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
37b00 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
37b10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
37b20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37b30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37b40 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
37b50 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
37b60 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
37b70 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
37b80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
37b90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
37ba0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
37bb0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
37bc0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
37bd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37be0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
37bf0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
37c00 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
37c10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37c20 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
37c30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
37c40 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
37c50 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
37c60 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
37c70 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
37c80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
37c90 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
37ca0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37cb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
37cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37cd0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
37ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37cf0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
37d00 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
37d10 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
37d20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37d30 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
37d40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
37d50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
37d60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
37d70 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
37d80 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
37d90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
37da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37db0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
37dc0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
37dd0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
37de0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37df0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
37e00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37e10 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
37e20 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
37e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
37e40 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
37e50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
37e60 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
37e70 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
37e80 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
37e90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
37ea0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
37eb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
37ec0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
37ed0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
37ee0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37ef0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
37f00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
37f10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
37f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37f30 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
37f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37f50 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
37f60 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
37f70 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
37f80 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
37f90 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
37fa0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
37fb0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
37fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
37fd0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
37fe0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37ff0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
38000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
38010 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
38020 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
38030 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
38040 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
38050 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
38060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
38070 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
38080 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
38090 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
380a0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
380b0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
380c0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
380d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
380e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
380f0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
38100 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
38110 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
38120 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
38130 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
38140 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
38150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
38160 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
38170 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
38180 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
38190 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
381a0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
381b0 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
381c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
381d0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
381e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
381f0 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
38200 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
38210 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
38220 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
38230 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
38240 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
38250 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
38260 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
38270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
38280 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
38290 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
382a0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
382b0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
382c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
382d0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
382e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
382f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
38300 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
38310 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
38320 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
38330 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20  ..** Hence, the 
38340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
38350 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
38360 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  .** is normally 
38370 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68  only useful with
38380 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  in the implement
38390 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70  ation of .** [ap
383a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
383b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
383c0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
383d0 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e  les], not within
383e0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70  .** top-level ap
383f0 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a  plication code..
38400 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20  **.** The these 
38410 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74  routines may att
38420 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
38430 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 20  the datatype of 
38440 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  the result..** ^
38450 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
38460 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
38470 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
38480 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
38490 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
384a0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
384b0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
384c0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
384d0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
384e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
384f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
38500 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
38510 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
38520 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
38530 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
38540 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
38550 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
38560 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
38570 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
38580 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
38590 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
385a0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
385b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
385c0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
385d0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
385e0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
385f0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
38600 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
38610 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
38620 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
38630 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
38640 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
38650 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
38660 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
38670 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
38680 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
38690 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
386a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
386b0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
386c0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
386d0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
386e0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
386f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
38700 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
38710 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
38720 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
38730 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
38740 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td&g