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

Artifact 088c510823fb965e4c47b8ded19f97a17e5e368b52753c145bcbd1af49890afa:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
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 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6910: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6930: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6940: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6950: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6960: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6970: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6980: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6990: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
69a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
69b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
69c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
69d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
69e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
69f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6a00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6a20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6a30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6a60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6a70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6a80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6aa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6ab0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6ac0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6ad0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6ae0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6af0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6b00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6b10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6b20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6b30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6b60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6b70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6b80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ba0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6bb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6bc0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6bd0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6be0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6bf0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6c00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6c20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6c30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6c40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6c50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6c60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6c70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6c80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6ca0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6cb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6cc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6cd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6ce0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6cf0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6d00: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6d10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6d20: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6d30: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6d40: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6d50: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6d60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6d70: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6d80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d90: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6dd0: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6de0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6df0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6e00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6e10: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6e20: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6e30: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6e40: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6e50: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6e60: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6e70: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6e80: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e90: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6eb0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6ec0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6ed0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6ee0: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6ef0: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6f00: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6f10: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6f20: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6f30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6f40: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6f50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6f60: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6f70: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6f80: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f90: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6fa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6fb0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6fc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6fd0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ff0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
7000: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
7030: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7040: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7070: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7090: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
70a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
70b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
70c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
70d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
70e0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
70f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7100: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7110: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7130: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7140: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7150: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7180: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
71a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
71b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
71c0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
71d0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
71e0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
71f0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7210: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7220: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7240: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7250: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7260: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
7270: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
7280: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
72c0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
72d0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
72e0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
72f0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7300: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7310: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7320: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7330: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7340: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7350: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7360: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7370: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
7380: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7390: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
73a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
73c0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
73d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
73e0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7400: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7420: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7430: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7440: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7450: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7460: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
7470: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
7480: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7490: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
74a0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
74b0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
74c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
74d0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
74e0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
74f0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7500: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7520: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7550: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7560: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
7570: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
7580: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7590: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
75a0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
75b0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
75c0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
75d0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
75e0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
75f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7610: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7620: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7630: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7640: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7650: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7660: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
7670: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
7680: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7690: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
76a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
76b0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
76c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
76d0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
76e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
76f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7700: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7710: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7720: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7730: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7740: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7750: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7760: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7770: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7780: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7790: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
77a0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
77b0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
77c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
77d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
77e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
77f0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7800: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7810: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7820: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7830: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7840: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7850: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7860: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7870: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7880: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7890: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
78a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
78b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
78c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
78d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
78e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
78f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7900: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7910: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7920: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7930: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7940: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7950: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7960: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7980: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7990: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
79a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
79b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
79c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
79d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
79f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7a00: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7a10: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7a50: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7a70: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7a80: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a90: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7ab0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7ac0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7ad0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7ae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7af0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7b00: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7b10: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7b20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7b30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7b40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7b50: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7b60: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7b70: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7b80: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b90: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7bb0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7bc0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7bd0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7be0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7c00: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7c10: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7c20: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7c30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7c40: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7c50: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7c60: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7c70: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c90: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7ca0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7cd0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7ce0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7d00: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7d10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7d20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7d30: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7d40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7d50: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7d60: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7d70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7d80: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d90: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7da0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7db0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7dc0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7de0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7df0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e00: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7e10: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7e20: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7e30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7e40: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7e50: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7e60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7e70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e80: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e90: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7ea0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7eb0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7ec0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7ed0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7ee0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7ef0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7f00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7f10: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7f20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7f30: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7f40: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f60: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7f70: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7f80: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f90: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7fa0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7fb0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7fc0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7fd0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7fe0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7ff0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
8000: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
8010: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
8020: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
8030: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
8040: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
8050: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
8060: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
8070: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
8080: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8090: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
80a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
80b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
80c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
80d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8100: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8120: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8130: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8140: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8150: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8160: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
8170: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
8180: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8190: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
81a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
81b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
81c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
81d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
81e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
81f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8200: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8210: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8220: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8230: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8240: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8250: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8260: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
8270: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
8280: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8290: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
82a0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
82c0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
82d0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
82e0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
82f0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8310: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8320: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8330: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8340: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8350: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8360: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
8370: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
8380: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8390: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
83a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
83b0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
83c0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
83d0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
83e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
83f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8400: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8410: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8420: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8430: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8440: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8450: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8460: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
8470: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
8480: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8490: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
84a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
84b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
84c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
84d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
84e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
84f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8500: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8510: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8520: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8530: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8540: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8550: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8560: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
8570: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
8580: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8590: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
85a0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
85b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
85c0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
85d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
85e0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
85f0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8600: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8610: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8630: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8640: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8650: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8660: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
8670: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
8680: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8690: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
86a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
86b0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
86c0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
86d0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
86e0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
86f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8700: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8710: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8720: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8730: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8740: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8750: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8760: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8770: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
8780: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8790: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
87a0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
87b0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
87c0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
87d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8810: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8830: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8890: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
88a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
88b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
88e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8910: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8920: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8930: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8960: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
8980: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8990: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
89a0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
89b0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
89c0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
89d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
89e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
89f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8a00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8a10: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8a20: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8a30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8a60: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8a70: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8a80: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a90: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8aa0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8ab0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8ac0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8ad0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8ae0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8b00: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8b10: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8b20: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b30: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8b40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b50: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8b60: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8b70: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8b80: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b90: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ba0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8bb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8bd0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8be0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8bf0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8c00: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8c10: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8c20: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8c30: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8c40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8c50: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8c60: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8c70: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8c80: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c90: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8ca0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8cb0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8cc0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8cd0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8ce0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8cf0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d00: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8d10: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8d20: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8d30: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8d50: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8d70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8d80: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d90: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8da0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8db0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8dc0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8dd0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8de0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8df0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8e00: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8e10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8e20: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8e30: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8e40: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8e50: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e70: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ea0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8eb0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8ee0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8ef0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8f00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8f10: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8f20: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8f30: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8f40: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8f50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8f60: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8f70: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f90: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8fa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8fb0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8fc0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8fd0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8fe0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8ff0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9000: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9010: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9020: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9030: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9040: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9050: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9060: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9070: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9080: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9090: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
90a0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
90b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
90c0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
90d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
90e0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9100: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9110: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9120: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9130: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9140: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9160: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9170: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9180: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9190: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
91a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
91b0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
91c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91e0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
91f0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9200: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9210: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9220: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9230: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9240: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9250: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9260: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
9270: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
9280: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9290: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
92a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
92b0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
92c0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
92d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
92e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
92f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9300: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9330: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9360: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9370: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9380: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9390: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
93a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
93b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
93c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
93d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
93e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
93f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9400: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9410: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9420: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9430: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9440: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9450: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9460: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9470: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
9480: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9490: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
94a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
94b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
94c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
94d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
94e0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
94f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9500: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9510: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9520: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9540: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9560: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
9570: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
9580: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9590: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
95a0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
95b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
95c0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
95d0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
95e0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
95f0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9600: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9610: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9620: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9630: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9640: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9650: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9660: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9670: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9680: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9690: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
96a0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
96b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
96c0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
96d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
96e0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d  E_FCNTL_SIZE_LIM
96f0: 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  IT]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c  ITE_FCNTL_SIZE_L
9710: 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  IMIT] opcode is 
9720: 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f 72  used by in-memor
9730: 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69 6d  y VFS that.** im
9740: 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74 65  plements [sqlite
9750: 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d  3_deserialize()]
9760: 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65 72   to set an upper
9770: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
9780: 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e 2d  ze.** of the in-
9790: 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e  memory database.
97a0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
97b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
97c0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
97d0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
97e0: 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  ger pointed to i
97f0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9800: 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69 6e   it is filled in
9810: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75 72   with the.** cur
9820: 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74 68  rent limit.  Oth
9830: 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69 74  erwise the limit
9840: 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20 6c   is set to the l
9850: 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61 6c  arger of the val
9860: 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e 74  ue.** of the int
9870: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9880: 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
9890: 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20 20  database size.  
98a0: 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 70  The integer.** p
98b0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65 74  ointed to is set
98c0: 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d 69   to the new limi
98d0: 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  t..**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
98f0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
9900: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
9910: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
9920: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
9930: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
9940: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
9950: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
9960: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
9970: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
9980: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
9990: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
99a0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
99b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
99c0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
99d0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
99e0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
99f0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
9a00: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
9a10: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
9a20: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
9a30: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
9a40: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
9a50: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
9a60: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
9a70: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
9a80: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
9a90: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
9aa0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
9ab0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
9ac0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9ad0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ae0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9af0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9b10: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9b20: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9b30: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9b40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9b50: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9b70: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9b80: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9b90: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9ba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9bb0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  AL_POINTER]..**.
9bc0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9bd0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9be0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9bf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9c00: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  RNAL_POINTER] op
9c10: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9c20: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
9c30: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
9c40: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
9c50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
9c60: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c   the journal fil
9c70: 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65  e (either.** the
9c80: 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e   [rollback journ
9c90: 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74  al] or the [writ
9ca0: 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f  e-ahead log]) fo
9cb0: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  r a particular d
9cc0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9cd0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9ce0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9cf0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  ILE_POINTER]..**
9d00: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9d10: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
9d20: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
9d30: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
9d40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9d50: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
9d60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9d70: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9d80: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9d90: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9da0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9db0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9dc0: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9dd0: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9de0: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9df0: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9e00: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9e10: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9e20: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
9e30: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9e40: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9e50: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
9e60: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
9e70: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9e80: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9e90: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9ea0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9eb0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9ec0: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9ed0: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9ee0: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9ef0: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9f00: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9f10: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
9f20: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
9f30: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9f40: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9f50: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
9f60: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
9f70: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9f80: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9f90: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9fa0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9fb0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9fc0: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9fd0: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9fe0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9ff0: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
a000: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
a010: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
a020: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
a030: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
a040: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a050: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
a060: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
a070: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
a080: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
a090: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
a0a0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
a0b0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
a0c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a0d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
a0e0: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
a0f0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
a100: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
a110: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
a120: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
a130: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
a140: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
a150: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
a160: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
a170: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
a180: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
a190: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
a1a0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
a1b0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
a1c0: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
a1d0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
a1e0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
a1f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
a200: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
a210: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a220: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
a230: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
a240: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
a250: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
a260: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
a270: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
a280: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
a290: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
a2a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
a2b0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
a2c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a2d0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
a2e0: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
a2f0: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
a300: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
a310: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
a320: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
a330: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
a340: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
a350: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
a360: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
a370: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
a380: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
a390: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
a3a0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
a3b0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
a3c0: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
a3d0: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
a3e0: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
a3f0: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
a400: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
a410: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
a420: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
a430: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
a440: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
a450: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
a460: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
a470: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
a480: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
a490: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
a4a0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
a4b0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
a4c0: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
a4d0: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
a4e0: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
a4f0: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
a500: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
a510: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
a520: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
a530: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
a540: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
a550: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
a560: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
a570: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
a580: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
a590: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
a5a0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
a5b0: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65  nteger is the ne
a5c0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
a5d0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
a5e0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
a5f0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
a600: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
a610: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
a620: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
a630: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
a640: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
a650: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
a660: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
a670: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
a680: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
a690: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
a6a0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
a6b0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
a6c0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
a6d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
a6e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
a6f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a700: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a730: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a740: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a750: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a760: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
a770: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
a780: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
a790: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
a7a0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
a7b0: 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61 6e   ([WAL file]) an
a7c0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 0a  d shared memory.
a7d0: 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ** files used fo
a7e0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
a7f0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
a800: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
a810: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
a820: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
a830: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
a840: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
a850: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
a860: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
a870: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
a880: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
a890: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
a8a0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
a8b0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
a8c0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
a8d0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
a8e0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
a8f0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
a900: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
a910: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
a920: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
a930: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
a940: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
a950: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a960: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
a970: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
a980: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
a990: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
a9a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a9b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a9c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a9d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a9e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a9f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
aa00: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
aa10: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
aa20: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
aa30: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
aa40: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
aa50: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
aa60: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
aa70: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
aa80: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
aa90: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
aaa0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
aab0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
aac0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aad0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
aae0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
aaf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ab00: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ab10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
ab20: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
ab30: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
ab40: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
ab50: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
ab60: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
ab70: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
ab80: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
ab90: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
aba0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
abb0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
abc0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
abd0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
abe0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
abf0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
ac00: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ac10: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
ac20: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
ac30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
ac40: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
ac50: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
ac60: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
ac70: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
ac80: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
ac90: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
aca0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
acb0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
acc0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
acd0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
ace0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
acf0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ad00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ad10: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
ad20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ad30: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
ad40: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
ad50: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
ad60: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
ad70: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
ad80: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
ad90: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
ada0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
adb0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
adc0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
add0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
ade0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
adf0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
ae00: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
ae10: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
ae20: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
ae30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ae40: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
ae50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ae60: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
ae70: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
ae80: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
ae90: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
aea0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
aeb0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
aec0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
aed0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
aee0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
aef0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
af00: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
af10: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
af20: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
af30: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
af40: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
af50: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
af60: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
af70: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
af80: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
af90: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
afa0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
afb0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
afc0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
afd0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
afe0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
aff0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
b000: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
b010: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
b020: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
b030: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
b040: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
b050: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
b060: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
b070: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
b080: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
b090: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
b0a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b0b0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
b0c0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
b0d0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
b0e0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
b0f0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
b100: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b110: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
b120: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b130: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b140: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69  INTER] opcode fi
b150: 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  nds a pointer to
b160: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a   the top-level.*
b170: 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e  * [VFSes] curren
b180: 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54  tly in use.  ^(T
b190: 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e  he argument X in
b1a0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  .** sqlite3_file
b1b0: 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49  _control(db,SQLI
b1c0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
b1d0: 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a  NTER,X) must be.
b1e0: 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c  ** of type "[sql
b1f0: 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20  ite3_vfs] **".  
b200: 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c  This opcodes wil
b210: 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61  l set *X.** to a
b220: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
b230: 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e  top-level VFS.)^
b240: 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20  .** ^When there 
b250: 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53  are multiple VFS
b260: 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74   shims in the st
b270: 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65  ack, this opcode
b280: 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70   finds the.** up
b290: 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e  per-most shim on
b2a0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
b2b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b2c0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
b2d0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
b2e0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
b2f0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
b300: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
b310: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b320: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
b330: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
b340: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
b350: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
b360: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
b370: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
b380: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
b390: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
b3a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
b3b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b3c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b3d0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
b3e0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
b3f0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
b400: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
b410: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
b420: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
b430: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
b440: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
b450: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
b470: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
b480: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
b490: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
b4a0: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
b4b0: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
b4c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b4d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
b4e0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
b4f0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
b500: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
b510: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
b520: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
b530: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b540: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
b550: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
b560: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
b570: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
b580: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
b590: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
b5a0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
b5b0: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
b5c0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
b5d0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
b5e0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
b5f0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
b600: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b610: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
b620: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
b630: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
b640: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b650: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b660: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b670: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
b680: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
b690: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
b6a0: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
b6b0: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
b6c0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
b6d0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
b6e0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
b6f0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
b700: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
b710: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
b720: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
b730: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
b740: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
b750: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
b760: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
b770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b780: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b790: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
b7a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
b7b0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
b7c0: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
b7d0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
b7e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
b7f0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
b800: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
b810: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
b820: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
b830: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
b840: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
b850: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
b860: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b870: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
b880: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
b890: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
b8a0: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
b8b0: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
b8c0: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
b8d0: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
b8e0: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
b8f0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
b900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b910: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b920: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
b930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b940: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
b950: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
b960: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
b970: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
b980: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
b990: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
b9a0: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
b9b0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
b9c0: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
b9d0: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
b9e0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
b9f0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
ba00: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
ba10: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
ba20: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
ba30: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
ba40: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
ba50: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
ba60: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
ba70: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
ba80: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
ba90: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
baa0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
bab0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
bac0: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
bad0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
bae0: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
baf0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
bb00: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
bb10: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
bb20: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
bb30: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
bb40: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
bb50: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
bb60: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
bb70: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bb80: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
bb90: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
bba0: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
bbb0: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
bbc0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bbd0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bbe0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
bbf0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
bc00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
bc10: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
bc20: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
bc30: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
bc40: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
bc50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bc60: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
bc70: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
bc80: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
bc90: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
bca0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
bcb0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
bcc0: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
bcd0: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
bce0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
bcf0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
bd00: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
bd10: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
bd20: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
bd30: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
bd40: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
bd50: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
bd60: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
bd70: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
bd80: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
bd90: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
bda0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
bdb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bdc0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
bdd0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bde0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
bdf0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
be00: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
be10: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
be20: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
be30: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
be40: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
be50: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
be60: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
be70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
be80: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
be90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
bea0: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
beb0: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
bec0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
bed0: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
bee0: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
bef0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
bf00: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
bf10: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
bf20: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
bf30: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
bf40: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
bf50: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
bf60: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
bf70: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
bf80: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
bf90: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
bfa0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
bfb0: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
bfc0: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
bfd0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
bfe0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
bff0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
c000: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
c010: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c020: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
c030: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c040: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
c050: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
c060: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
c070: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
c080: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
c090: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
c0a0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
c0b0: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
c0c0: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
c0d0: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
c0e0: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
c0f0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
c100: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
c110: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
c120: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
c130: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
c140: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
c150: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
c160: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
c170: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c180: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
c190: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
c1a0: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
c1b0: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
c1c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
c1e0: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
c1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c200: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
c210: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c220: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c230: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
c240: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
c250: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
c260: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
c270: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
c280: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
c290: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
c2a0: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
c2b0: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
c2c0: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
c2d0: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
c2e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c2f0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
c300: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
c310: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c320: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
c330: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c340: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c350: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
c360: 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  g native file ha
c370: 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  ndle associated 
c380: 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64  with a file hand
c390: 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a  le.  This file.*
c3a0: 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  * control interp
c3b0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c3c0: 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t as a pointer t
c3d0: 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20  o a native file 
c3e0: 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72  handle and.** wr
c3f0: 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69  ites the resulti
c400: 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a  ng value there..
c410: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c430: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
c440: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c450: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c460: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
c470: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
c480: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
c490: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
c4a0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
c4b0: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
c4c0: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
c4d0: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
c4e0: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
c4f0: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
c500: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
c510: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
c520: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
c530: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
c540: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
c550: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
c560: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c580: 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CK]].** The [SQL
c590: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5a0: 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c  OCK] is a signal
c5b0: 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65   to the VFS laye
c5c0: 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a  r that it might.
c5d0: 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f  ** be advantageo
c5e0: 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74  us to block on t
c5f0: 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b  he next WAL lock
c600: 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20   if the lock is 
c610: 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  not immediately.
c620: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  ** available.  T
c630: 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d  he WAL subsystem
c640: 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67   issues this sig
c650: 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a  nal during rare.
c660: 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  ** circumstances
c670: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78   in order to fix
c680: 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20   a problem with 
c690: 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69  priority inversi
c6a0: 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  on..** Applicati
c6b0: 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e  ons should <em>n
c6c0: 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73  ot</em> use this
c6d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a   file-control..*
c6e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c6f0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d  E_FCNTL_ZIPVFS]]
c700: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c710: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70  FCNTL_ZIPVFS] op
c720: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c730: 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e  ted by zipvfs on
c740: 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a  ly. All other.**
c750: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c760: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c770: 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  ND for this opco
c780: 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  de..**.** <li>[[
c790: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c7a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c7b0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63  E_FCNTL_RBU] opc
c7c0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c7d0: 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61  ed by the specia
c7e0: 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a  l VFS used by.**
c7f0: 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69   the RBU extensi
c800: 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74  on only.  All ot
c810: 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72  her VFS should r
c820: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c830: 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69  FOUND for.** thi
c840: 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  s opcode.  .**.*
c850: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c860: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c870: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20  C_WRITE]].** If 
c880: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c890: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c8a0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74  RITE] opcode ret
c8b0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20  urns SQLITE_OK, 
c8c0: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65  then.** the file
c8d0: 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70   descriptor is p
c8e0: 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20  laced in "batch 
c8f0: 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69  write mode", whi
c900: 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20  ch.** means all 
c910: 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65  subsequent write
c920: 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c   operations will
c930: 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64   be deferred and
c940: 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61   done.** atomica
c950: 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20  lly at the next 
c960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c970: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c980: 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20  E].  Systems.** 
c990: 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70  that do not supp
c9a0: 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63  ort batch atomic
c9b0: 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74   writes will ret
c9c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c9d0: 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69  UND..** ^Followi
c9e0: 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  ng a successful 
c9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ca00: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IN_ATOMIC_WRITE 
ca10: 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20  and prior to.** 
ca20: 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c  the closing [SQL
ca30: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ca40: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ca50: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  r.** [SQLITE_FCN
ca60: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
ca70: 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74  IC_WRITE], SQLit
ca80: 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e  e will make.** n
ca90: 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  o VFS interface 
caa0: 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d  calls on the sam
cab0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
cac0: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
cad0: 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63  .** except for c
cae0: 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69  alls to the xWri
caf0: 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68  te method and th
cb00: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
cb10: 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53  ethod.** with [S
cb20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
cb30: 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _HINT]..**.** <l
cb40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
cb50: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cb60: 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RITE]].** The [S
cb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
cb80: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
cb90: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61   opcode causes a
cba0: 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72  ll write.** oper
cbb0: 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65  ations since the
cbc0: 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73   previous succes
cbd0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a  sful call to .**
cbe0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
cbf0: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
cc00: 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d  E] to be perform
cc10: 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a  ed atomically..*
cc20: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
cc30: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
cc40: 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f  ITE_OK] if and o
cc50: 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65  nly if the write
cc60: 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65  s were.** all pe
cc70: 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66  rformed successf
cc80: 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65  ully and have be
cc90: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20  en committed to 
cca0: 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61  persistent stora
ccb0: 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  ge..** ^Regardle
ccc0: 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
ccd0: 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65   not it is succe
cce0: 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65  ssful, this file
ccf0: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a   control takes.*
cd00: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
cd10: 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74  iptor out of bat
cd20: 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f  ch write mode so
cd30: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
cd40: 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70  uent.** write op
cd50: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64  erations are ind
cd60: 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51  ependent..** ^SQ
cd70: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
cd80: 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43  invoke SQLITE_FC
cd90: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
cda0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
cdb0: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
cdc0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
cdd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
cde0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
cdf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ce00: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
ce10: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  CK_ATOMIC_WRITE]
ce20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ce30: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
ce40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
ce50: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
ce60: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
ce70: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
ce80: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
ce90: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
cea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
ceb0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
cec0: 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  to be rolled bac
ced0: 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65  k..** ^This file
cee0: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74   control takes t
cef0: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cf00: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cf10: 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f  write mode.** so
cf20: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
cf30: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
cf40: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cf50: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cf60: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cf70: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cf80: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cf90: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
cfa0: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
cfb0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
cfc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cfd0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
cfe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cff0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
d000: 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MEOUT]].** The [
d010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d020: 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64  K_TIMEOUT] opcod
d030: 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70 74  e causes attempt
d040: 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  s to obtain.** a
d050: 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67   file lock using
d060: 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53   the xLock or xS
d070: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f  hmLock methods o
d080: 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61 69  f the VFS to wai
d090: 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d  t.** for up to M
d0a0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
d0b0: 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77 68  fore failing, wh
d0c0: 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69 6e  ere M is the sin
d0d0: 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64  gle .** unsigned
d0e0: 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 74   integer paramet
d0f0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
d100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
d110: 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54  A_VERSION]].** T
d120: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d130: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 6f  _DATA_VERSION] o
d140: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
d150: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d160: 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73 65  to.** a database
d170: 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67 75   file.  The argu
d180: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
d190: 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75 6e  r to a 32-bit un
d1a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
d1b0: 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65 72  ** The "data ver
d1c0: 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70 61  sion" for the pa
d1d0: 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69  ger is written i
d1e0: 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72 2e  nto the pointer.
d1f0: 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20 76    The.** "data v
d200: 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73 20  ersion" changes 
d210: 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68 61  whenever any cha
d220: 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74 68  nge occurs to th
d230: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
d240: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
d250: 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67 68  , either through
d260: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
d270: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
d280: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
d290: 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74 72  on or through tr
d2a0: 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d 69  ansactions commi
d2b0: 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74 65  tted by separate
d2c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
d2d0: 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 6c  nections possibl
d2e0: 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  y in other proce
d2f0: 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 74  sses. The [sqlit
d300: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
d310: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
d320: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d330: 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74 61  find if any data
d340: 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e 6e  base on the conn
d350: 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e 67  ection has chang
d360: 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 20  ed,.** but that 
d370: 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e  interface respon
d380: 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f 6e  ds to changes on
d390: 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 73   TEMP as well as
d3a0: 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a 2a   MAIN and does.*
d3b0: 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  * not provide a 
d3c0: 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74  mechanism to det
d3d0: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20 4d  ect changes to M
d3e0: 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c  AIN only.  Also,
d3f0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
d400: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
d410: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70  ] interface resp
d420: 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61 6c  onds to internal
d430: 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 6e   changes only an
d440: 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e 67  d.** omits chang
d450: 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65 72  es made by other
d460: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d470: 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 5b  tions.  The.** [
d480: 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73  PRAGMA data_vers
d490: 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 6f  ion] command pro
d4a0: 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73 6d  vide a mechanism
d4b0: 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67   to detect chang
d4c0: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c  es to.** a singl
d4d0: 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
d4e0: 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20 64  ase that occur d
d4f0: 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74 61  ue to other data
d500: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d510: 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 63  ,.** but omits c
d520: 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e 74  hanges implement
d530: 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
d540: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e  se connection on
d550: 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a 20   which it is.** 
d560: 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 69  called.  This fi
d570: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 68  le control is th
d580: 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 6d  e only mechanism
d590: 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67   to detect chang
d5a0: 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 65  es that.** happe
d5b0: 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61  n either interna
d5c0: 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c 6c  lly or externall
d5d0: 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20 61  y and that are a
d5e0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
d5f0: 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  * a particular a
d600: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
d610: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  ..** </ul>.*/.#d
d620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d630: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
d640: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
d650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d660: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
d670: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
d680: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d690: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
d6a0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
d6b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d6c0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
d6d0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
d6e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d6f0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
d700: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
d710: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
d720: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
d730: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
d740: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
d750: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
d760: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
d770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d780: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
d790: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
d7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d7b0: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
d7c0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
d7d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
d7e0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
d7f0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
d800: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
d810: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
d820: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
d830: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
d840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d850: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
d860: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
d870: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
d880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d890: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
d8b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d8c0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
d8d0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
d8e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d8f0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
d900: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
d910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d920: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
d930: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
d940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d950: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
d960: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
d970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d980: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
d990: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
d9a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d9b0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
d9c0: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
d9d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d9e0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
d9f0: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
da00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
da10: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
da20: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
da30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
da40: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
da50: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
da60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
da70: 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  FS              
da80: 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51     25.#define SQ
da90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20  LITE_FCNTL_RBU  
daa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dab0: 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    26.#define SQL
dac0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
dad0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
dae0: 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   27.#define SQLI
daf0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
db00: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
db10: 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  28.#define SQLIT
db20: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
db30: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
db40: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
db50: 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20  _FCNTL_PDB      
db60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30                30
db70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
db90: 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a  IC_WRITE     31.
dba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dbb0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
dbc0: 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23  IC_WRITE    32.#
dbd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dbe0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64  MIC_WRITE  33.#d
dc00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dc10: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20  TL_LOCK_TIMEOUT 
dc20: 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64 65            34.#de
dc30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dc40: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20 20  L_DATA_VERSION  
dc50: 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65 66           35.#def
dc60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dc70: 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20 20  _SIZE_LIMIT     
dc80: 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20 64          36../* d
dc90: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
dca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dcb0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
dcc0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
dcd0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
dce0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
dcf0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
dd00: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
dd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
dd20: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
dd30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
dd40: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
dd50: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
dd60: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
dd70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
dd80: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
dd90: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
dda0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
ddb0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
ddc0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
ddd0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
dde0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
ddf0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
de00: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
de10: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
de20: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
de30: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
de40: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
de50: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
de60: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
de70: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
de80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
de90: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
dea0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
deb0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
dec0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
ded0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
dee0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
def0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
df00: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
df10: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
df20: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
df30: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
df40: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
df50: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
df60: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
df70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
df80: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
df90: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
dfa0: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
dfb0: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
dfc0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
dfd0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
dfe0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
dff0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
e000: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
e010: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e020: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
e030: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
e040: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
e050: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
e060: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
e070: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
e080: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e090: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
e0a0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
e0b0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
e0c0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
e0d0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
e0e0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
e0f0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
e100: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
e110: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
e120: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
e130: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
e140: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
e150: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
e160: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
e170: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
e180: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
e190: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78   is sometimes ex
e1a0: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67  tended by adding
e1b0: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74   new methods ont
e1c0: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45  o.** the end.  E
e1d0: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e  ach time such an
e1e0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72   extension occur
e1f0: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  s, the iVersion 
e200: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72  field.** is incr
e210: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56  emented.  The iV
e220: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61  ersion value sta
e230: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e  rted out as 1 in
e240: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e250: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64  ion 3.5.0] on [d
e260: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68  ateof:3.5.0], th
e270: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20  en increased to 
e280: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65  2.** with SQLite
e290: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d   [version 3.7.0]
e2a0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
e2b0: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63  0], and then inc
e2c0: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77  reased.** to 3 w
e2d0: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73  ith SQLite [vers
e2e0: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64  ion 3.7.6] on [d
e2f0: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41  ateof:3.7.6].  A
e300: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
e310: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e  .** may be appen
e320: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ded to the sqlit
e330: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e  e3_vfs object an
e340: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  d the iVersion v
e350: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72  alue.** may incr
e360: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75  ease again in fu
e370: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e380: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65   SQLite..** Note
e390: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
e3a0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
e3b0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
e3c0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
e3d0: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a  transition from.
e3e0: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
e3f0: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65  on 3.5.9] to [ve
e400: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20  rsion 3.6.0] on 
e410: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a  [dateof:3.6.0].*
e420: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  * and yet the iV
e430: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
e440: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a   not modified..*
e450: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e460: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e470: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e480: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e490: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e4a0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e4b0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e4c0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e4d0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e4e0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e4f0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e500: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e510: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e520: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e530: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e540: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e550: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e560: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e580: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e590: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e5a0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e5b0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e5c0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e5d0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e5e0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e5f0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e600: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e610: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e620: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e640: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e650: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e660: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e670: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e680: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e690: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e6a0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e6b0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e6c0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e6d0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e6e0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e6f0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e700: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e710: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e720: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e730: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e740: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e750: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e760: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e780: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e790: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e7a0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e7b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e7c0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e7d0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e7e0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e7f0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e800: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e810: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e820: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e830: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e840: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e850: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
e860: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
e870: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
e880: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
e890: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
e8a0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
e8b0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
e8c0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
e8d0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
e8e0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
e8f0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
e900: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
e910: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
e920: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
e930: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
e940: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
e950: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
e960: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
e970: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
e980: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
e990: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
e9a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
e9b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
e9c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
e9d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
e9e0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
e9f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ea00: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ea10: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ea20: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ea30: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ea40: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ea50: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ea60: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ea70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ea80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ea90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
eaa0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
eab0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
eac0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ead0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
eae0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
eaf0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
eb00: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
eb10: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
eb20: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
eb30: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
eb40: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
eb50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
eb60: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
eb70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
eb80: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
eb90: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
eba0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ebb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ebc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ebd0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ebe0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ebf0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
ec00: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
ec10: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
ec20: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
ec30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
ec40: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
ec50: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
ec60: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
ec70: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
ec80: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
ec90: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
eca0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ecb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
ecc0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
ecd0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
ece0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
ecf0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
ed00: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
ed10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
ed20: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
ed30: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
ed40: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
ed50: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
ed60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
ed70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ed80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
ed90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
eda0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
edb0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
edc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
edd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ede0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
edf0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ee00: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
ee10: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
ee20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
ee30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ee40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
ee50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
ee60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ee70: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
ee80: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
ee90: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
eea0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
eeb0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
eec0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
eed0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
eee0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
eef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
ef00: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
ef10: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
ef20: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
ef30: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
ef40: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
ef50: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
ef60: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
ef70: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
ef80: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
ef90: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
efa0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
efb0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
efc0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
efd0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
efe0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
eff0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
f000: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
f010: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
f020: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
f030: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
f040: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
f050: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
f060: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
f070: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
f080: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
f090: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
f0a0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
f0b0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
f0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
f0d0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
f0e0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
f0f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
f100: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f110: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
f120: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f130: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
f140: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
f150: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f160: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
f170: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f180: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
f190: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
f1a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
f1b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f1c0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
f1d0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f1e0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f1f0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f200: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f210: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f230: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f240: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f250: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f260: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f280: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f290: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f2a0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f2b0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f2c0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f2d0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f2e0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f2f0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f300: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f310: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f320: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f330: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f350: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f360: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f370: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f380: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f390: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f3a0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f3b0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f3c0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f3d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f3e0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f3f0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f400: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f410: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f420: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f430: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f440: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f460: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f470: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f480: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f490: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f4a0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f4b0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f4c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f4d0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f4e0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f4f0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f500: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f510: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f520: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f530: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f540: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f560: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f570: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f580: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f590: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f5a0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f5b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f5c0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f5d0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f5e0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f5f0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f600: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f610: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f620: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f630: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f640: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f650: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f660: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f670: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f680: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f690: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f6a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f6b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f6c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f6d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f6e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f6f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f700: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f720: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f730: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f740: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f750: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f760: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f770: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f790: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f7a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f7b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f7c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f7d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f7e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f7f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f800: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f810: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f820: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f830: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f840: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f850: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
f860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
f870: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
f880: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
f890: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
f8a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
f8b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
f8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
f8d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
f8e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
f8f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
f900: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
f910: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
f920: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
f930: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
f940: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
f950: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
f960: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f970: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
f980: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
f990: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
f9a0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
f9b0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
f9c0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
f9d0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
f9e0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
f9f0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
fa00: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
fa10: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
fa20: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
fa30: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
fa40: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
fa50: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
fa60: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
fa70: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
fa80: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
fa90: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
faa0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
fab0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
fac0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
fad0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
fae0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
faf0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
fb00: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
fb10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
fb20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
fb30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
fb40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
fb50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
fb60: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
fb70: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
fb80: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
fb90: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fba0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
fbb0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
fbc0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
fbd0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fbe0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fbf0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fc00: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fc10: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fc20: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fc30: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fc40: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fc50: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fc60: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fc70: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
fc80: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fc90: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fca0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fcb0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fcc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fcd0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fce0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fcf0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fd00: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
fd10: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fd20: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fd30: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fd40: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
fd50: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
fd60: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
fd70: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
fd80: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
fd90: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
fda0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
fdb0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
fdc0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
fdd0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
fde0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
fdf0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
fe00: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
fe10: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
fe20: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
fe30: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
fe40: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
fe50: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
fe60: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
fe70: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
fe80: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
fe90: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
fea0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
feb0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
fec0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
fed0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
fee0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
fef0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
ff00: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
ff10: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
ff20: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
ff30: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
ff40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
ff50: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
ff60: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
ff70: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
ff80: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
ff90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
ffa0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
ffb0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
ffc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
ffd0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
ffe0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
fff0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
10000 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
10010 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
10020 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
10030 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
10040 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
10050 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
10060 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10070 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
10080 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
10090 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
100a0 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
100b0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
100c0 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
100d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
100e0 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
100f0 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
10100 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
10110 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
10120 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
10130 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
10140 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
10150 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
10160 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
10170 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
10180 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
10190 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
101a0 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
101b0 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
101c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
101d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
101e0 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
101f0 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
10200 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10210 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
10220 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
10230 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
10240 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
10250 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
10260 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10270 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
10280 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
10290 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
102a0 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
102b0 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
102c0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
102d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
102e0 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
102f0 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
10300 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10310 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10320 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10330 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
10340 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
10350 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10370 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
10380 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
10390 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
103a0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
103b0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
103c0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
103d0 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
103e0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
103f0 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
10400 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
10410 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
10420 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
10430 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
10440 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
10450 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
10460 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
10470 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
10480 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10490 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
104a0 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
104b0 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
104c0 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
104d0 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
104e0 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
104f0 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
10500 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
10510 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
10520 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
10530 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
10540 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
10550 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10560 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
10570 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
10580 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
10590 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
105a0 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
105b0 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
105c0 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
105d0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
105e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
105f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
10600 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10610 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10620 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
10630 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
10640 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10650 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
10660 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
10670 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
10680 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
10690 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
106a0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
106b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
106c0 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
106d0 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
106e0 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
106f0 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10700 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10710 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
10720 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
10730 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
10740 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10750 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
10760 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10770 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
10780 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
10790 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
107a0 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
107b0 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
107c0 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
107d0 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
107e0 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
107f0 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
10800 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
10810 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
10820 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
10830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10840 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
10850 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10860 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10870 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
10880 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
10890 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
108a0 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
108b0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
108c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
108d0 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
108e0 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
108f0 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10900 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10910 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10920 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10930 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10940 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10950 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10960 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10970 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10980 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10990 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
109a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
109b0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
109c0 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
109d0 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
109e0 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
109f0 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10a00 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10a10 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10a20 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10a30 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10a40 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10a50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10a60 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10a70 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10a80 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10a90 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10aa0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10ab0 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10ac0 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10ad0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10ae0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10af0 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10b00 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10b10 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b20 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10b30 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10b40 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10b50 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10b60 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10b70 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10b80 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10b90 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10ba0 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10bb0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10bc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10bd0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10be0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10bf0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10c00 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10c10 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10c20 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10c40 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10c50 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10c60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10c70 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10c80 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10c90 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10ca0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10cb0 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10cc0 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10cd0 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10ce0 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10cf0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10d00 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10d10 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10d20 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10d30 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10d40 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10d50 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10d60 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10d70 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10d80 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10d90 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10da0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10db0 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10dc0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10dd0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10de0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10df0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10e00 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10e10 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10e20 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10e30 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10e40 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10e50 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10e60 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10e70 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10e80 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10e90 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
10ea0 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
10eb0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
10ec0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
10ed0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
10ee0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10ef0 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
10f00 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
10f10 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
10f20 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
10f30 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
10f40 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
10f50 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
10f60 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10f70 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
10f80 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
10f90 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
10fa0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
10fb0 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
10fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10fd0 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
10fe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ff0 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
11000 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
11010 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
11020 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
11030 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
11040 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
11050 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
11060 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
11070 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
11080 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
11090 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
110a0 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
110b0 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
110c0 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
110d0 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
110e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
110f0 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
11100 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
11110 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
11120 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
11130 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
11140 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11150 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
11160 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
11170 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11180 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
11190 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
111a0 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
111b0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
111c0 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
111d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
111e0 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
111f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11200 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
11210 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
11220 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
11230 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
11240 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
11250 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
11260 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
11270 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
11280 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
11290 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
112a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
112b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
112c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
112d0 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
112e0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
112f0 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
11300 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11310 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11320 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
11330 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
11340 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
11350 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
11360 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
11390 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
113a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
113b0 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
113c0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
113d0 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
113e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
113f0 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
11400 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
11410 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
11420 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11430 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11440 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11450 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
11460 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
11470 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
11480 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11490 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
114a0 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
114b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
114c0 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
114d0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
114e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
114f0 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
11500 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
11510 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
11520 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
11530 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
11540 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
11550 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
11560 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11570 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11580 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
11590 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
115a0 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
115b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
115c0 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
115d0 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
115e0 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
115f0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
11600 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
11610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
11620 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
11630 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
11640 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
11650 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
11660 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
11670 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
11680 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
11690 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
116a0 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
116b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
116c0 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
116d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
116e0 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
116f0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
11700 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
11710 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
11720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11730 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11740 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11750 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11760 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
11770 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
11780 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11790 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
117a0 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
117b0 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
117c0 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
117d0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
117e0 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
117f0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
11800 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
11810 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
11820 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
11830 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
11840 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11850 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11860 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11870 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
11880 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
11890 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
118a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
118b0 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
118c0 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
118d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
118e0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
118f0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11900 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11910 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11920 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11930 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11940 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11950 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11960 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11980 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11990 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
119a0 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
119b0 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
119c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
119d0 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
119e0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
119f0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11a00 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11a10 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11a20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11a30 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11a40 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11a50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11a60 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11a70 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11a80 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11a90 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11aa0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11ab0 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11ac0 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11ad0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11ae0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11af0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11b00 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11b10 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11b20 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11b30 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11b40 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11b50 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11b60 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11b70 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11b80 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11b90 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11ba0 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11bb0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11bc0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11bd0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11be0 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11bf0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11c00 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11c10 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11c20 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11c30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11c40 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11c50 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11c60 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11c70 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11c80 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11c90 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11ca0 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11cb0 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11cc0 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11cd0 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11ce0 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11cf0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11d00 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11d10 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11d20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11d30 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11d40 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11d50 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11d60 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11d70 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11d80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11d90 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11da0 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11dc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11dd0 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11de0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11df0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11e00 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11e10 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11e20 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11e30 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11e40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11e50 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11e60 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11e70 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11e80 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11e90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11ea0 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
11eb0 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
11ec0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
11ed0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11ee0 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
11ef0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
11f00 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
11f10 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
11f20 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
11f30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
11f40 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11f50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11f60 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
11f70 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11f80 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
11f90 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
11fa0 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
11fb0 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
11fc0 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
11fd0 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
11fe0 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
11ff0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
12000 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
12010 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
12020 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
12030 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
12040 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
12050 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
12060 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
12070 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
12080 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
12090 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
120a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
120b0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
120c0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
120d0 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
120e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
120f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
12100 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
12110 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
12120 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
12130 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
12140 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
12150 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12160 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
12170 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
12180 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
12190 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
121a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
121b0 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
121c0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
121d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
121e0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
121f0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12200 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
12210 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
12220 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
12230 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
12240 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
12250 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
12260 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
12270 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
12290 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
122a0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
122b0 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
122c0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
122d0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
122e0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
122f0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
12300 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
12310 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
12320 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
12330 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12340 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12350 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
12360 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12370 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
12380 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
12390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
123a0 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
123b0 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
123c0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
123d0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
123e0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
123f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12400 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
12410 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
12420 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
12430 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
12440 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
12450 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12460 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
12470 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
12480 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
12490 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
124a0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
124b0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
124c0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
124d0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
124e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
124f0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
12500 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
12510 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
12520 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
12530 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
12540 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
12550 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
12560 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
12570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12580 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
12590 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
125a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
125b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
125c0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
125d0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
125e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
125f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
12600 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
12610 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
12620 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
12630 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
12640 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
12650 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
12660 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12670 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
12680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
12690 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
126a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
126b0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
126c0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
126d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
126e0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
126f0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
12700 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
12710 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
12720 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
12730 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12740 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
12750 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
12760 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
12770 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
12780 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12790 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
127a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
127b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
127c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
127d0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
127e0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
127f0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
12800 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12810 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
12820 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
12830 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
12840 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
12850 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
12860 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
12870 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
12880 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
12890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
128a0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
128b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
128c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
128d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
128e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
128f0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
12900 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
12910 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12920 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
12930 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
12940 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12950 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12960 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12980 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
12990 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
129a0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
129b0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
129c0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
129d0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
129e0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
129f0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
12a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
12a10 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
12a20 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
12a30 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
12a40 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
12a50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12a60 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12a70 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12a80 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
12a90 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
12aa0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
12ab0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12ac0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
12ad0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
12ae0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
12af0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12b00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12b10 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
12b20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
12b30 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
12b40 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12b50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12b60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12b70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12b80 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
12b90 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
12ba0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12bb0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
12bc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
12bd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
12be0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
12bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12c00 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
12c10 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
12c20 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12c30 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
12c40 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12c50 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12c60 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12c70 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12c80 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12c90 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12ca0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12cb0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12cc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
12cd0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
12ce0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
12cf0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
12d00 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
12d10 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
12d20 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
12d30 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
12d40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12d50 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12d60 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12d70 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12d80 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12d90 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12da0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12db0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
12dc0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
12dd0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
12de0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
12df0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
12e00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12e10 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
12e20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
12e30 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
12e40 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
12e50 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12e60 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
12e70 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12e80 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
12e90 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
12ea0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
12eb0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
12ec0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
12ed0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
12ee0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
12ef0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
12f00 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
12f10 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
12f20 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
12f30 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
12f40 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
12f50 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
12f60 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
12f70 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
12f80 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12f90 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
12fa0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12fb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12fc0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
12fd0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
12fe0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
12ff0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
13000 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
13010 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
13020 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
13030 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
13040 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
13050 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
13060 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
13070 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
13080 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
13090 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
130a0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
130b0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
130c0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
130d0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
130e0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
130f0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
13100 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
13110 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
13120 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
13130 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
13140 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
13150 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
13160 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
13170 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
13180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13190 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
131a0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
131b0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
131c0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
131d0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
131e0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
131f0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
13200 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
13210 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
13220 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
13230 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13240 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
13250 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
13260 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
13270 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
13280 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
13290 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
132a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132c0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
132d0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
132e0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
132f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13300 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
13310 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
13320 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
13330 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
13340 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
13350 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
13360 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
13370 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
13380 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
13390 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
133a0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
133b0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
133c0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
133d0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
133e0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
133f0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
13400 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
13410 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13420 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
13430 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
13440 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
13450 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
13460 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
13470 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
13480 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
13490 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
134a0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
134b0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
134c0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
134d0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
134e0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
134f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13500 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
13510 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
13520 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
13530 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
13540 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
13550 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
13560 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
13570 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
13580 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
13590 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
135a0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
135b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
135c0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
135d0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
135e0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
135f0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
13600 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
13610 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
13620 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
13630 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13640 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
13650 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
13660 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
13670 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
13680 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
13690 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
136a0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
136b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
136c0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
136d0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
136e0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
136f0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
13700 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
13710 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
13720 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
13730 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13740 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
13750 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
13760 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13770 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
13780 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
13790 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
137a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
137b0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
137c0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
137d0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
137e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
137f0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
13800 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
13810 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
13820 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13830 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
13840 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13850 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
13860 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
13870 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13880 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
13890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
138a0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
138b0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
138c0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
138d0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
138e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
138f0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13900 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13910 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13920 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13930 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13940 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13950 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13960 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13970 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13980 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
13990 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
139a0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
139b0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
139c0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
139d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
139e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
139f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
13a00 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13a10 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13a20 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13a30 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13a40 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13a50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13a60 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13a70 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13a80 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13a90 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13aa0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13ab0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13ac0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
13ad0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13af0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13b00 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13b10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13b20 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13b30 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13b50 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13b60 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13b70 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13b80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13b90 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
13ba0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
13bb0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13bc0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
13bd0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
13be0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13bf0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
13c00 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
13c10 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13c20 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13c30 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13c40 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13c50 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13c60 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13c70 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13c80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13c90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13ca0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13cb0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
13cc0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13cd0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13ce0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
13cf0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
13d00 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
13d10 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13d20 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13d30 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13d40 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13d50 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13d60 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13d70 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13d80 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13d90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13da0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13db0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
13dc0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
13dd0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
13de0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
13df0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
13e00 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
13e10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13e20 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
13e30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13e40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13e60 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13e70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e80 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13e90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13ea0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
13eb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ec0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
13ed0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13ee0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13ef0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13f00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13f10 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13f20 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
13f30 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
13f40 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13f50 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13f60 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13f80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13f90 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
13fa0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13fb0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
13fc0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
13fd0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
13fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ff0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
14000 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
14010 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
14020 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
14030 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
14040 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
14050 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
14060 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
14070 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
14080 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
14090 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
140a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
140b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
140c0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
140d0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
140e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
140f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14100 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14110 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14120 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14130 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
14140 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
14150 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
14160 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
14170 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
14180 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14190 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
141a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
141b0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
141c0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
141d0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
141e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
141f0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
14200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14210 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
14220 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14230 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
14240 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14250 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14260 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14270 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
14280 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
14290 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
142a0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
142b0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
142c0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
142d0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
142e0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
142f0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
14300 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14310 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
14320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14330 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
14340 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
14350 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
14360 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
14370 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
14380 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14390 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
143a0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
143b0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
143c0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
143d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
143e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
143f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
14400 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
14410 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
14420 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
14430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14440 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
14450 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
14460 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
14470 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
14480 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14490 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
144a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
144b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
144c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
144d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
144e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
144f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
14500 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
14510 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
14520 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
14530 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
14540 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
14560 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14570 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
14580 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14590 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
145a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
145b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
145d0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
145e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
145f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14600 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14610 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14620 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14630 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14640 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14650 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14660 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14670 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14680 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
14690 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
146a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
146b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
146c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
146d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
146e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
146f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14700 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14710 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
14720 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
14730 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
14740 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
14750 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14770 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
14780 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
14790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
147a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
147b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
147c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
147d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
147e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
147f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14800 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14810 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
14820 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14830 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14840 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14850 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14860 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14870 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14880 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
14890 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
148a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
148b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
148c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
148d0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
148e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
148f0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
14900 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
14910 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14920 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14930 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14940 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14950 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14960 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14970 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14980 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14990 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
149a0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
149b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
149c0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  SMALL_MALLOC]] <
149d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
149e0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64  _SMALL_MALLOC</d
149f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14a10 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  ALL_MALLOC optio
14a20 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14a30 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79  rgument of.** ty
14a40 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
14a50 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14a60 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20  , which if true 
14a70 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20  provides a hint 
14a80 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61  to.** SQLite tha
14a90 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69  t it should avoi
14aa0 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  d large memory a
14ab0 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f  llocations if po
14ac0 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74  ssible..** SQLit
14ad0 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65  e will run faste
14ae0 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20  r if it is free 
14af0 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65  to make large me
14b00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14b10 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70  ,.** but some ap
14b20 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
14b30 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c  prefer to run sl
14b40 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65  ower in exchange
14b50 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65   for.** guarante
14b60 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20  es about memory 
14b70 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68  fragmentation th
14b80 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20  at are possible 
14b90 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f  if large.** allo
14ba0 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69  cations are avoi
14bb0 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ded.  This hint 
14bc0 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e  is normally off.
14bd0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14be0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14bf0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
14c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14c10 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
14c20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14c30 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14c40 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14c50 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14c60 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14c70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14c80 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14c90 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14ca0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14cb0 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
14cc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14cd0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14ce0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14cf0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
14d00 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
14d10 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
14d20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
14d30 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
14d40 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14d50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14d60 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14d70 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14d80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14d90 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14da0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14db0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
14dc0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14dd0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
14de0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
14df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14e00 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
14e10 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
14e20 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
14e30 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
14e40 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14e50 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14e60 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14e70 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14e80 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14e90 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14ea0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14ec0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
14ed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14ee0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
14ef0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14f10 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  H option is no l
14f20 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c  onger used..** <
14f30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14f50 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14f60 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14f70 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14f80 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14f90 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
14fa0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14fb0 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
14fc0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
14fd0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
14fe0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
14ff0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
15000 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
15010 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
15020 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
15030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
15040 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
15050 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15060 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
15080 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
15090 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
150a0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
150b0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
150c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
150d0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
150e0 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
150f0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
15100 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
15110 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
15120 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
15130 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
15140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
15150 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
15160 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
15170 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
15180 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
15190 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
151a0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
151b0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
151c0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
151d0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
151e0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
151f0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
15200 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15210 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15220 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15230 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15240 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
15250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15260 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
15270 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
15280 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
15290 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
152a0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
152b0 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
152c0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
152d0 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
152e0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
152f0 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
15300 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
15310 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
15320 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
15330 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
15340 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
15350 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
15360 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
15370 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
15380 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
15390 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
153a0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
153b0 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
153c0 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
153d0 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
153e0 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
153f0 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
15400 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
15410 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
15420 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
15430 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
15440 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
15450 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
15460 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
15470 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
15480 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
15490 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
154a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
154b0 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
154c0 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
154d0 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
154e0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
154f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15500 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
15510 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
15520 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
15530 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
15540 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
15550 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
15560 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
15570 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
15580 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
15590 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
155a0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
155b0 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
155c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
155d0 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
155e0 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
155f0 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
15600 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
15610 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
15620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15630 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15660 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15670 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
15680 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15690 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
156a0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
156b0 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
156c0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
156d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
156e0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
156f0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
15700 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
15710 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
15720 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
15730 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
15740 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15750 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
15760 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
15770 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
15780 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
15790 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
157a0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
157b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
157c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
157d0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
157e0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
157f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
15800 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15810 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
15820 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
15830 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
15840 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
15850 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
15860 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
15870 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
15880 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
15890 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
158a0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
158b0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
158c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
158d0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
158e0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
158f0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
15900 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
15910 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
15920 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
15930 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
15940 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15960 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15970 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
15980 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
15990 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
159a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
159b0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
159c0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
159d0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
159e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
159f0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
15a00 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15a10 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
15a20 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
15a30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
15a40 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
15a50 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
15a60 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
15a70 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
15a80 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15a90 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
15aa0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
15ab0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
15ac0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
15ad0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15ae0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
15af0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
15b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b10 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
15b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15b30 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15b40 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15b50 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
15b60 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15b70 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15b80 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
15b90 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
15ba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15bb0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15bc0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
15bd0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15be0 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
15bf0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
15c00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
15c10 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
15c20 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
15c30 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
15c40 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
15c50 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
15c60 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
15c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15c80 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15c90 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
15ca0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
15cb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15cc0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
15cd0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15ce0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15cf0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15d00 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15d10 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15d20 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15d30 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15d40 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15d50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15d60 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15d70 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15d90 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15dc0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
15dd0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15de0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
15df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
15e00 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
15e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15e20 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
15e30 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15e40 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
15e50 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15e70 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15e80 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15e90 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15eb0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15ec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
15ed0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
15ee0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
15ef0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
15f00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
15f10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
15f20 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15f40 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15f50 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
15f60 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
15f70 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15f80 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15f90 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15fa0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15fb0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
15fc0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
15fd0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
16040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
16050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
16060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
16070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
16080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
16090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
160a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
160b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
160c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
160d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
160e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
160f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16100 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16110 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
16120 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16130 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
16140 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16150 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
16160 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
16170 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
16180 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
16190 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
161a0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
161b0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
161c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
161d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
161e0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
161f0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16200 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16210 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
16220 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16230 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
16240 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
16250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16260 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
16270 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
16280 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
16290 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
162a0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
162b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
162c0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
162d0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
162e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
162f0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
16300 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16310 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16320 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
16330 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
16340 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16360 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
16370 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
16380 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16390 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
163a0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
163b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
163c0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
163d0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
163e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
163f0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16400 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
16410 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
16420 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
16430 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
16440 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16450 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
16460 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
16470 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
16480 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
16490 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
164a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
164b0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
164c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
164d0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
164e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
164f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16500 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
16510 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16520 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
16530 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16540 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16550 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16560 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
16570 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
16580 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
16590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
165a0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
165b0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
165c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
165d0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
165e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
165f0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
16600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16610 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16620 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
16630 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
16640 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
16650 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
16660 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
16670 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16680 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
16690 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
166a0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
166b0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
166c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
166d0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
166e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
166f0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
16700 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16710 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
16720 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
16730 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
16740 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
16750 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
16760 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
16770 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
16780 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
16790 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
167a0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
167b0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
167c0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
167d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
167e0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
167f0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
16800 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
16810 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16820 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
16830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16840 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16850 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
16860 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
16870 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
16880 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
16890 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
168a0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
168b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
168c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
168d0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
168e0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
168f0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
16900 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
16910 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
16920 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16930 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
16940 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16950 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16960 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16970 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
16980 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
16990 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
169a0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
169b0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
169c0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
169d0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
169e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
169f0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
16a00 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16a10 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
16a20 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
16a30 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
16a40 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
16a50 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16a60 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16a70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
16a80 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
16a90 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16ab0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16ac0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
16ad0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16ae0 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
16af0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16b00 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
16b10 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
16b20 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
16b30 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16b40 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
16b50 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
16b60 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
16b70 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16b80 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
16b90 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
16ba0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16bb0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
16bc0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
16bd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16be0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
16bf0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
16c00 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
16c10 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
16c20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
16c30 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
16c40 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16c50 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
16c60 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
16c70 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
16c80 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
16c90 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16ca0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
16cb0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16cc0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
16cd0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
16ce0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
16cf0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
16d00 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
16d10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
16d20 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
16d30 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
16d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16d50 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
16d60 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
16d70 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16d80 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
16d90 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
16da0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
16db0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
16dc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
16dd0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
16de0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
16df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
16e00 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16e10 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
16e20 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16e30 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
16e40 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16e50 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16e60 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
16e70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
16e80 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
16e90 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
16ea0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
16eb0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
16ec0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16ed0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
16ee0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
16ef0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
16f00 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
16f10 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
16f20 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16f30 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
16f40 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
16f50 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
16f60 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16f80 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
16f90 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
16fa0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16fb0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
16fc0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
16fd0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
16fe0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16ff0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
17000 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
17010 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
17020 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
17030 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
17040 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
17050 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
17060 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
17070 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
17080 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
17090 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
170a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
170b0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
170c0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
170d0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
170e0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
170f0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
17100 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
17110 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
17120 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17130 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
17140 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
17150 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17160 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
17170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17180 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
17190 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
171a0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
171b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
171c0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
171d0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
171e0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
171f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
17200 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
17210 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
17220 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17230 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
17240 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17250 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
17260 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
17270 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
17280 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
17290 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
172a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
172b0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
172c0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
172d0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
172e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
172f0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
17300 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
17310 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
17320 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
17330 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
17340 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
17350 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
17360 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
17370 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
17380 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
17390 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
173a0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
173b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
173c0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
173d0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
173e0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
173f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17400 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
17410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17420 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
17430 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17440 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
17450 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
17460 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17470 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
17480 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
17490 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
174a0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
174b0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
174c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
174d0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
174e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
174f0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
17500 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
17510 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
17520 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
17530 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
17540 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
17550 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
17560 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
17570 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17580 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
17590 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
175a0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
175b0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
175c0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
175d0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
175e0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
175f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17600 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
17610 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
17620 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
17630 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
17640 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
17650 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
17660 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17670 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
17680 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17690 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
176a0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
176b0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
176c0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
176d0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
176e0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
176f0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
17700 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
17710 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
17720 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
17730 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
17740 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
17750 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
17760 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
17770 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
17780 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
17790 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
177a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
177b0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
177c0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
177d0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
177e0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
177f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17800 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
17810 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
17820 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
17830 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
17840 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
17850 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
17860 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
17870 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
17880 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
17890 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
178a0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
178b0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
178c0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
178d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
178e0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
178f0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
17900 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
17910 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17920 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
17930 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
17940 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17950 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17970 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
17980 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17990 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
179a0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
179b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
179c0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
179d0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
179e0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
179f0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
17a00 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
17a10 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
17a20 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
17a30 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
17a40 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
17a50 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17a60 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
17a70 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
17a80 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
17a90 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
17aa0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
17ab0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
17ac0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
17ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17ae0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
17af0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17b00 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
17b10 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17b20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17b30 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
17b40 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17b50 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17b60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17b70 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
17b80 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
17b90 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
17ba0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
17bb0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
17bc0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
17bd0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
17be0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
17bf0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
17c00 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
17c10 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
17c20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
17c30 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
17c40 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
17c50 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
17c60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17c70 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
17c80 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17c90 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
17ca0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17cb0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
17cc0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17cd0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17ce0 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
17cf0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
17d00 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
17d10 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
17d20 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
17d30 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
17d40 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
17d50 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
17d60 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
17d70 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17d80 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
17d90 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
17da0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
17db0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
17dc0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
17dd0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
17de0 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
17df0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
17e00 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
17e10 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
17e20 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
17e30 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
17e40 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
17e50 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
17e60 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
17e70 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
17e80 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
17e90 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
17ea0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
17eb0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
17ec0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17ed0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
17ee0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17ef0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17f00 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
17f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17f20 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
17f30 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17f40 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17f50 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
17f60 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
17f70 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
17f80 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
17f90 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
17fa0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
17fb0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
17fc0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
17fd0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
17fe0 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
17ff0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
18000 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
18010 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
18020 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
18030 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
18040 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
18050 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
18060 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
18070 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
18080 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
18090 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
180a0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
180b0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
180c0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
180d0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
180e0 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
180f0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
18100 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
18110 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
18120 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
18130 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
18140 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
18150 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
18160 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
18170 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
18180 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
18190 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
181a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
181b0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
181c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
181d0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
181e0 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  REF_SIZE.** <dd>
181f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18200 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
18210 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20   option accepts 
18220 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
18230 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69  er.** of type (i
18240 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61  nt) - the new va
18250 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65  lue of the sorte
18260 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65  r-reference size
18270 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55   threshold..** U
18280 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c  sually, when SQL
18290 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65  ite uses an exte
182a0 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64  rnal sort to ord
182b0 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72  er records accor
182c0 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52  ding.** to an OR
182d0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61  DER BY clause, a
182e0 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72  ll fields requir
182f0 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
18300 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20   are present in 
18310 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65  the.** sorted re
18320 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20  cords. However, 
18330 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  if SQLite determ
18340 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68  ines based on th
18350 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a  e declared type.
18360 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f  ** of a table co
18370 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61  lumn that its va
18380 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  lues are likely 
18390 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65  to be very large
183a0 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61   - larger.** tha
183b0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64  n the configured
183c0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
183d0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
183e0 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65   - then a refere
183f0 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64  nce.** is stored
18400 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20   in each sorted 
18410 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72  record and the r
18420 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76  equired column v
18430 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20  alues loaded.** 
18440 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
18450 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65  e as records are
18460 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72   returned in sor
18470 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64  ted order. The d
18480 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
18490 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
184a0 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20  is to never use 
184b0 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
184c0 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20  n. Specifying a 
184d0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c  .** negative val
184e0 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69  ue for this opti
184f0 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20  on restores the 
18500 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75  default behaviou
18510 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  r..** This optio
18520 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
18530 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
18540 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
18550 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
18560 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45  ABLE_SORTER_REFE
18570 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d  RENCES] compile-
18580 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  time option..**.
18590 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
185a0 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
185b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
185c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41  _CONFIG_MEMDB_MA
185d0 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  XSIZE.** <dd>The
185e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
185f0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70 74  EMDB_MAXSIZE opt
18600 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69  ion accepts a si
18610 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ngle parameter.*
18620 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  * [sqlite3_int64
18630 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  ] parameter whic
18640 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
18650 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66 6f   maximum size fo
18660 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a  r an in-memory.*
18670 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  * database creat
18680 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18690 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d  3_deserialize()]
186a0 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74 20  .  This default 
186b0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20  maximum.** size 
186c0 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64 20  can be adjusted 
186d0 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20 69  up or down for i
186e0 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62 61  ndividual databa
186f0 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ses using the.**
18700 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
18710 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c 69  IZE_LIMIT] [sqli
18720 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
18730 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20  |file-control]. 
18740 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66   If this.** conf
18750 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69 6e  iguration settin
18760 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 2c  g is never used,
18770 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
18780 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65 74  t maximum is det
18790 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
187a0 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42 5f  e [SQLITE_MEMDB_
187b0 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45 5d  DEFAULT_MAXSIZE]
187c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
187d0 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a 2a  tion.  If that.*
187e0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
187f0 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65 74  ption is not set
18800 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
18810 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31 30  lt maximum is 10
18820 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64  73741824..** </d
18830 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18850 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18860 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
18880 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
18890 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
188a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
188b0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
188c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
188d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
188e0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
188f0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18900 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18910 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18920 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18930 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18940 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18950 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18960 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
18970 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72   6  /* No longer
18980 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
18990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
189a0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
189b0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
189c0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
189d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
189e0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
189f0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18a00 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
18a10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
18a30 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
18a40 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
18a60 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
18a70 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
18a80 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18a90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18aa0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
18ab0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
18ac0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
18ad0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
18ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
18af0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
18b00 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
18b10 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
18b20 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
18b30 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
18b40 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18b50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18b60 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
18b70 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
18b80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18b90 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
18ba0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
18bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18bc0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
18bd0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
18be0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18c00 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
18c10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18c30 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
18c40 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18c50 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c70 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
18c80 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
18c90 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
18ca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18cb0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
18cc0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
18cd0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18ce0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18cf0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
18d00 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
18d10 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
18d30 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
18d40 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
18d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d70 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
18d80 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
18d90 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
18da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18db0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
18dc0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
18dd0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
18de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18df0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
18e00 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
18e10 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
18e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e30 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18e40 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
18e50 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
18e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e70 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
18e80 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20  LLOC        27  
18e90 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
18ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18eb0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
18ec0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69  ZE      28  /* i
18ed0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18ee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18ef0 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20  G_MEMDB_MAXSIZE 
18f00 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71 6c        29  /* sql
18f10 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f  ite3_int64 */../
18f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
18f30 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
18f40 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
18f50 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
18f60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
18f70 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
18f80 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
18f90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
18fa0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
18fb0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
18fc0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
18fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
18fe0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
18ff0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
19000 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
19010 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
19020 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
19030 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
19040 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
19050 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19060 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
19070 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
19080 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
19090 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
190a0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
190b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
190c0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
190d0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
190e0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
190f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
19100 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
19110 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
19120 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
19130 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
19140 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
19150 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
19160 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
19170 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
19180 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
19190 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
191a0 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  DE]].** <dt>SQLI
191b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
191c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
191d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
191e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
191f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19200 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
19210 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
19220 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
19230 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
19240 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
19250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19260 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
19270 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
19280 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
19290 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
192a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
192b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
192c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
192d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
192e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
192f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
19300 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
19310 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19320 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
19330 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
19340 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
19350 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
19360 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
19370 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
19380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19390 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
193a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
193b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
193c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
193d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
193e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
193f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
19400 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
19410 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
19420 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
19430 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
19440 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
19450 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
19460 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
19470 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
19480 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
19490 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
194a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
194b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
194c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
194d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
194e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
194f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
19500 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
19510 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
19520 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
19530 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
19540 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
19550 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
19560 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
19570 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
19580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19590 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
195a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
195b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
195c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
195d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
195e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
195f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
19600 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
19610 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
19620 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
19630 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
19640 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
19650 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
19660 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
19670 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
19680 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19690 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
196a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
196b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
196c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
196d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
196e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
196f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
19700 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
19710 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
19720 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d  FIG_ENABLE_FKEY]
19730 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
19740 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19750 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
19760 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19770 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19780 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
19790 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
197a0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
197b0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
197c0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
197d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
197e0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
197f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19800 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19810 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19820 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19830 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
19840 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
19850 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
19860 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
19870 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
19880 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
19890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
198a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
198b0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
198c0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
198d0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
198e0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
198f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
19900 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
19910 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19920 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
19930 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
19940 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19950 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
19960 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
19970 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
19980 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
19990 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
199a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
199b0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a  NABLE_TRIGGER]].
199c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
199d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
199e0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
199f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19a00 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
19a10 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
19a20 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
19a30 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
19a40 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19a50 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19a60 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19a80 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19a90 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19aa0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
19ab0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19ac0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
19ad0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19ae0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
19af0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
19b00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19b10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19b20 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19b30 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19b40 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19b50 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
19b60 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
19b70 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
19b80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
19b90 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
19ba0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
19bb0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19bc0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19bd0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
19be0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19bf0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19c00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
19c10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c20 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19c30 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  R]].** <dt>SQLIT
19c40 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19c50 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19c60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19c70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19c80 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19c90 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 5b  disable the.** [
19ca0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19cb0 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68  ] function which
19cc0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
19cd0 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74  ** [FTS3] full-t
19ce0 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e  ext search engin
19cf0 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20  e extension..** 
19d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
19d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
19d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
19d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
19d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
19d60 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
19d70 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74  er() or.** posit
19d80 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74  ive to enable ft
19d90 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
19da0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
19db0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
19dc0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ** unchanged..**
19dd0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19de0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19df0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19e00 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
19e10 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19e20 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19e30 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69  ther fts3_tokeni
19e40 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
19e50 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19e60 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19e70 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19e80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19e90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19ea0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19eb0 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
19ec0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
19ed0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
19ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19ef0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19f00 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a 20  _EXTENSION]].** 
19f10 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19f20 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
19f30 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
19f40 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19f50 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19f60 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
19f70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
19f80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
19f90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
19fa0 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
19fb0 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
19fc0 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
19fd0 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
19fe0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
19ff0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
1a000 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1a010 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
1a020 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
1a030 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a040 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
1a050 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
1a060 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
1a070 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
1a080 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
1a090 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
1a0a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a0b0 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
1a0c0 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
1a0d0 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
1a0e0 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
1a0f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1a100 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
1a110 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
1a120 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a130 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1a140 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
1a150 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
1a160 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
1a170 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
1a180 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
1a190 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
1a1a0 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
1a1b0 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
1a1c0 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
1a1d0 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
1a1e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
1a1f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a200 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a210 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a220 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a230 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a240 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a250 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
1a260 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
1a270 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
1a280 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
1a290 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1a2a0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
1a2b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
1a2c0 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
1a2d0 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
1a2e0 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
1a2f0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
1a300 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
1a310 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1a320 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
1a330 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  NAME]] <dt>SQLIT
1a340 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a350 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
1a360 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a370 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
1a380 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
1a390 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
1a3a0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
1a3b0 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
1a3c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a3d0 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
1a3e0 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
1a3f0 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
1a400 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
1a410 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
1a420 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
1a430 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
1a440 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
1a450 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
1a460 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
1a470 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
1a480 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
1a490 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
1a4a0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
1a4b0 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
1a4c0 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
1a4d0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
1a4e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a4f0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
1a500 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1a510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1a520 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 0a  KPT_ON_CLOSE]] .
1a530 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a540 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
1a550 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  N_CLOSE</dt>.** 
1a560 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68  <dd> Usually, wh
1a570 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e  en a database in
1a580 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f   wal mode is clo
1a590 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20  sed or detached 
1a5a0 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62  from a .** datab
1a5b0 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69  ase handle, SQLi
1a5c0 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69  te checks if thi
1a5d0 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74  s will mean that
1a5e0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e   there are now n
1a5f0 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  o .** connection
1a600 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20  s at all to the 
1a610 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c  database. If so,
1a620 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63   it performs a c
1a630 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70  heckpoint .** op
1a640 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63  eration before c
1a650 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65  losing the conne
1a660 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69  ction. This opti
1a670 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  on may be used t
1a680 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68  o.** override th
1a690 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68  is behaviour. Th
1a6a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a6b0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
1a6c0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73   operation.** is
1a6d0 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f   an integer - po
1a6e0 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c  sitive to disabl
1a6f0 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  e checkpoints-on
1a700 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20  -close, or zero 
1a710 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29  (the.** default)
1a720 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c   to enable them,
1a730 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f   and negative to
1a740 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1a750 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
1a760 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a770 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a780 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a790 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69  .** into which i
1a7a0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a7b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a7c0 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  ther checkpoints
1a7d0 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76  -on-close.** hav
1a7e0 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  e been disabled 
1a7f0 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20  - 0 if they are 
1a800 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
1a810 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20  if they are..** 
1a820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a830 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a840 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74 3e  ABLE_QPSG]] <dt>
1a850 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a860 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e  ENABLE_QPSG</dt>
1a870 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
1a880 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a890 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e  ABLE_QPSG option
1a8a0 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
1a8b0 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65  activates.** the
1a8c0 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20   [query planner 
1a8d0 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e  stability guaran
1a8e0 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68  tee] (QPSG).  Wh
1a8f0 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61  en the QPSG is a
1a900 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67  ctive,.** a sing
1a910 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61  le SQL query sta
1a920 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61  tement will alwa
1a930 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  ys use the same 
1a940 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64  algorithm regard
1a950 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65  less.** of value
1a960 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  s of [bound para
1a970 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51  meters].)^ The Q
1a980 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d  PSG disables som
1a990 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61  e query optimiza
1a9a0 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f  tions.** that lo
1a9b0 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73  ok at the values
1a9c0 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65   of bound parame
1a9d0 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20  ters, which can 
1a9e0 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65  make some querie
1a9f0 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75  s.** slower.  Bu
1aa00 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74  t the QPSG has t
1aa10 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20  he advantage of 
1aa20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65  more predictable
1aa30 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68   behavior.  With
1aa40 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74  .** the QPSG act
1aa50 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ive, SQLite will
1aa60 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
1aa70 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20  same query plan 
1aa80 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a  in the field as.
1aa90 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69  ** was used duri
1aaa0 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68  ng testing in th
1aab0 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69  e lab..** The fi
1aac0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1aad0 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
1aae0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
1aaf0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
1ab00 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70   .** the QPSG, p
1ab10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1ab20 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74  e QPSG, or negat
1ab30 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1ab40 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
1ab50 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e  anged. The secon
1ab60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1ab70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1ab80 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1ab90 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
1aba0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1abb0 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51  te whether the Q
1abc0 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20  PSG is disabled 
1abd0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
1abe0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1abf0 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l..** </dd>.**.*
1ac00 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1ac10 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 5d  FIG_TRIGGER_EQP]
1ac20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1ac30 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1ac40 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42  P</dt>.** <dd> B
1ac50 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f  y default, the o
1ac60 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e  utput of EXPLAIN
1ac70 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d   QUERY PLAN comm
1ac80 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a  ands does not .*
1ac90 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74  * include output
1aca0 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69   for any operati
1acb0 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ons performed by
1acc0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1acd0 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f  s. This.** optio
1ace0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  n is used to set
1acf0 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64   or clear (the d
1ad00 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74  efault) a flag t
1ad10 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73  hat governs this
1ad20 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68  .** behavior. Th
1ad30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ad40 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
1ad50 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1ad60 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f   integer -.** po
1ad70 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1ad80 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67   output for trig
1ad90 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72  ger programs, or
1ada0 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65   zero to disable
1adb0 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74   it,.** or negat
1adc0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1add0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1ade0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1adf0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1ae00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1ae10 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1ae20 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a  h is written .**
1ae30 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1ae40 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70  ate whether outp
1ae50 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20  ut-for-triggers 
1ae60 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65  has been disable
1ae70 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20  d - 0 if .** it 
1ae80 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c  is not disabled,
1ae90 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a   1 if it is.  .*
1aea0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1aeb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1aec0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d 5d  RESET_DATABASE]]
1aed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1aee0 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1aef0 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ASE</dt>.** <dd>
1af00 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f   Set the SQLITE_
1af10 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1af20 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64  ATABASE flag and
1af30 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41   then run.** [VA
1af40 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74  CUUM] in order t
1af50 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62 61  o reset a databa
1af60 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d  se back to an em
1af70 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pty database.** 
1af80 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61  with no schema a
1af90 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54  nd no content. T
1afa0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
1afb0 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20  cess works even 
1afc0 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63  for.** a badly c
1afd0 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61 73  orrupted databas
1afe0 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a  e file:.** <ol>.
1aff0 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 64  ** <li> If the d
1b000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b010 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 6e  on is newly open
1b020 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 74  ed, make sure it
1b030 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a 2a   has read the.**
1b040 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 73        database s
1b050 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72 69  chema by prepari
1b060 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64 69  ng then discardi
1b070 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61 67  ng some query ag
1b080 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 20  ainst the.**    
1b090 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 63    database, or c
1b0a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 74  alling sqlite3_t
1b0b0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
1b0c0 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e 67  data(), ignoring
1b0d0 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 72   any.**      err
1b0e0 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70 20  ors.  This step 
1b0f0 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 72  is only necessar
1b100 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61  y if the applica
1b110 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f 20  tion desires to 
1b120 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 65  keep.**      the
1b130 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c   database in WAL
1b140 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65 20   mode after the 
1b150 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73 20  reset if it was 
1b160 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 6f  in WAL mode befo
1b170 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 72  re.**      the r
1b180 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20  eset.  .** <li> 
1b190 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
1b1a0 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 43  g(db, SQLITE_DBC
1b1b0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1b1c0 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20  BASE, 1, 0);.** 
1b1d0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 78  <li> [sqlite3_ex
1b1e0 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 4d  ec](db, "[VACUUM
1b1f0 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  ]", 0, 0, 0);.**
1b200 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62   <li> sqlite3_db
1b210 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49  _config(db, SQLI
1b220 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b230 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20 30  T_DATABASE, 0, 0
1b240 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42  );.** </ol>.** B
1b250 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e 67  ecause resetting
1b260 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 64   a database is d
1b270 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20 69  estructive and i
1b280 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68 65  rreversible, the
1b290 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71 75  .** process requ
1b2a0 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66 20  ires the use of 
1b2b0 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50 49  this obscure API
1b2c0 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 74   and multiple st
1b2d0 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 65  eps to help.** e
1b2e0 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64 6f  nsure that it do
1b2f0 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 79  es not happen by
1b300 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a   accident..**.**
1b310 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
1b320 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20 3c  IG_DEFENSIVE]] <
1b330 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1b340 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 74  IG_DEFENSIVE</dt
1b350 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1b360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1b370 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 63  ENSIVE option ac
1b380 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
1b390 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 64  ivates the.** "d
1b3a0 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 66  efensive" flag f
1b3b0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
1b3c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20  nnection.  When 
1b3d0 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a 2a  the defensive.**
1b3e0 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 64   flag is enabled
1b3f0 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 75  , language featu
1b400 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 6f  res that allow o
1b410 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 0a  rdinary SQL to .
1b420 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20  ** deliberately 
1b430 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 61  corrupt the data
1b440 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 69  base file are di
1b450 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 73  sabled.  The dis
1b460 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 65  abled.** feature
1b470 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 72  s include but ar
1b480 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 6f  e not limited to
1b490 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
1b4a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1b4b0 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 74  The [PRAGMA writ
1b4c0 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20  able_schema=ON] 
1b4d0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c  statement..** <l
1b4e0 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68 65  i> Writes to the
1b4f0 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65 5d   [sqlite_dbpage]
1b500 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
1b510 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20 77  ** <li> Direct w
1b520 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f 77  rites to [shadow
1b530 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f 75   tables]..** </u
1b540 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c  l>.** </dd>.** <
1b550 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1b560 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b570 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
1b580 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
1b590 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
1b5a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b5b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
1b5c0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
1b5d0 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
1b5e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b5f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1b600 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
1b610 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
1b620 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b630 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1b640 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
1b650 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
1b660 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b670 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b680 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
1b690 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
1b6a0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b6b0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b6c0 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
1b6d0 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
1b6e0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b6f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b700 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
1b710 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
1b720 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b740 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1b750 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37  G           1007
1b760 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b780 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1b790 45 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30  EQP           10
1b7a0 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  08 /* int int* *
1b7b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b7c0 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1b7d0 44 41 54 41 42 41 53 45 20 20 20 20 20 20 20 20  DATABASE        
1b7e0 31 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1009 /* int int*
1b7f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b800 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45  TE_DBCONFIG_DEFE
1b810 4e 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  NSIVE           
1b820 20 20 31 30 31 30 20 2f 2a 20 69 6e 74 20 69 6e    1010 /* int in
1b830 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b840 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1b850 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  X               
1b860 20 20 20 20 31 30 31 30 20 2f 2a 20 4c 61 72 67      1010 /* Larg
1b870 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a  est DBCONFIG */.
1b880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b890 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1b8a0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1b8b0 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
1b8c0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b8d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1b8e0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1b8f0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
1b900 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1b910 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
1b920 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1b930 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
1b940 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
1b950 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
1b960 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
1b970 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
1b980 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
1b990 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
1b9a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1b9b0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
1b9c0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
1b9d0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1b9e0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
1b9f0 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
1ba00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1ba10 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
1ba20 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
1ba30 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
1ba40 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1ba50 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
1ba60 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
1ba70 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
1ba80 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
1ba90 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
1baa0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
1bab0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
1bac0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
1bad0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
1bae0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
1baf0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
1bb00 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
1bb10 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
1bb20 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
1bb30 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
1bb40 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
1bb50 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
1bb60 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
1bb70 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
1bb80 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
1bb90 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
1bba0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
1bbb0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
1bbc0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1bbd0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
1bbe0 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
1bbf0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
1bc00 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
1bc10 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
1bc20 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
1bc30 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
1bc40 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
1bc50 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
1bc60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
1bc70 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
1bc80 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1bc90 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
1bca0 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
1bcb0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1bcc0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
1bcd0 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
1bce0 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
1bcf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bd00 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
1bd10 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1bd20 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
1bd30 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
1bd40 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
1bd50 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
1bd60 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
1bd70 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
1bd80 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
1bd90 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
1bda0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1bdb0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
1bdc0 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
1bdd0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1bde0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1bdf0 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
1be00 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
1be10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1be20 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
1be30 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1be40 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
1be50 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
1be60 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
1be70 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
1be80 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
1be90 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
1bea0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
1beb0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bec0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
1bed0 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
1bee0 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
1bef0 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
1bf00 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
1bf10 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
1bf20 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
1bf30 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
1bf40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1bf50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
1bf60 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
1bf70 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
1bf80 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
1bf90 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
1bfa0 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
1bfb0 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
1bfc0 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
1bfd0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1bfe0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bff0 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1c000 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1c010 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1c020 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1c030 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1c040 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1c050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1c060 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1c070 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1c080 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1c090 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1c0a0 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1c0b0 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1c0c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1c0d0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1c0e0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1c0f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1c100 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1c110 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1c120 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1c130 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1c140 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1c150 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1c160 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1c170 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1c180 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1c190 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1c1a0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1c1b0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1c1c0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1c1d0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1c1e0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1c1f0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1c200 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1c210 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1c220 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1c230 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1c240 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1c250 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1c260 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1c270 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1c280 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1c290 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1c2a0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1c2b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1c2c0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1c2d0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1c2e0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1c2f0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1c300 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1c310 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1c320 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1c330 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1c340 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1c350 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1c360 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1c370 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1c380 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1c390 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1c3a0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1c3b0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1c3c0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1c3d0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1c3e0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1c3f0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1c400 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1c410 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1c420 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1c430 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1c440 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1c450 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1c460 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1c470 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1c480 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1c490 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1c4a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1c4b0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1c4c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c4d0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1c4e0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1c4f0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1c500 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1c510 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1c520 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c530 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1c540 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1c550 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1c560 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1c570 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1c580 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1c590 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1c5a0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1c5b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c5c0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c5d0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1c5e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c5f0 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1c600 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1c610 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1c620 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1c630 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1c640 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1c650 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1c660 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1c670 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1c680 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c690 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1c6a0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c6b0 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1c6c0 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1c6d0 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1c6e0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1c6f0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1c700 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c710 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1c720 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1c730 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1c740 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1c750 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1c760 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c770 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c780 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1c790 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1c7a0 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1c7b0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1c7c0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1c7d0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1c7e0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c7f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1c800 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1c810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c820 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1c830 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1c840 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1c850 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1c860 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1c870 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1c880 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1c890 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1c8a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1c8b0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1c8c0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1c8d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1c8e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1c8f0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1c900 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1c910 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1c920 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1c930 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1c940 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1c950 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1c960 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1c970 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1c980 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1c990 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1c9a0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1c9b0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1c9c0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1c9d0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1c9e0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1c9f0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1ca00 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1ca10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1ca20 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1ca30 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1ca40 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1ca50 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1ca60 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1ca70 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1ca80 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1ca90 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1caa0 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1cab0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1cac0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1cad0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1cae0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1caf0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1cb00 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1cb10 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1cb20 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1cb30 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1cb40 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1cb50 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1cb60 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1cb70 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1cb80 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1cb90 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1cba0 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1cbb0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1cbc0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1cbd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1cbe0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1cbf0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1cc00 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1cc10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1cc20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1cc30 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1cc40 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1cc50 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1cc60 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1cc70 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1cc80 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1cc90 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1cca0 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1ccb0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1ccc0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1ccd0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1cce0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1ccf0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1cd00 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1cd10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1cd20 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1cd30 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1cd40 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1cd50 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1cd60 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1cd70 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1cd80 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1cd90 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1cda0 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1cdb0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1cdc0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1cdd0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1cde0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1cdf0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1ce00 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1ce10 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1ce20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1ce30 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1ce40 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1ce50 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1ce60 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1ce70 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1ce80 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1ce90 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1cea0 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1ceb0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1cec0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1ced0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1cee0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1cef0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1cf00 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1cf10 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1cf20 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1cf30 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1cf40 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1cf50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1cf60 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1cf70 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1cf80 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1cf90 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1cfa0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1cfb0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1cfc0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1cfd0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  rigger..**.** If
1cfe0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1cff0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1d000 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1d010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d020 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1d030 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1d040 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1d050 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d060 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1d070 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1d080 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ningful..**.** S
1d090 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e  ee also:.** <ul>
1d0a0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71  .** <li> the [sq
1d0b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1d0c0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1d0d0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1d0e0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1d0f0 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1d100 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1d110 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1d120 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1d130 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f  on pragma].** </
1d140 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul>.*/.int sqlit
1d150 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1d160 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1d170 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1d180 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1d190 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1d1a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1d1b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1d1c0 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1d1d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1d1e0 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1d1f0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1d200 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1d210 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1d220 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1d230 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1d240 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1d250 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1d260 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1d270 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1d280 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1d290 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1d2a0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1d2b0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1d2c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1d2d0 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1d2e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d2f0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1d300 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1d310 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1d320 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1d330 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1d340 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1d350 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1d360 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1d370 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1d380 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1d390 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1d3a0 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1d3b0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1d3c0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1d3d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1d3e0 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1d3f0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1d400 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1d410 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e  l_changes(D)] in
1d420 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
1d430 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  orts the number.
1d440 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20  ** of rows that 
1d450 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53  changed due to S
1d460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  QL statement run
1d470 20 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73   against databas
1d480 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
1d490 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20  D.  Any changes 
1d4a0 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  by other databas
1d4b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72  e connections ar
1d4c0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f  e ignored..** To
1d4d0 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
1d4e0 61 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61  against a databa
1d4f0 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68  se file from oth
1d500 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  er database.** c
1d510 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74  onnections use t
1d520 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  he [PRAGMA data_
1d530 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
1d540 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   or the.** [SQLI
1d550 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
1d560 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e  RSION] [file con
1d570 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  trol]..** .** If
1d580 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1d590 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1d5a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1d5b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5c0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1d5d0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1d5e0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1d5f0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1d600 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1d610 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1d620 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1d630 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a  *.** See also:.*
1d640 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74  * <ul>.** <li> t
1d650 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1d660 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1d670 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1d680 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1d690 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1d6a0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1d6b0 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1d6c0 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1d6d0 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  on pragma].** <l
1d6e0 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  i> the [SQLITE_F
1d6f0 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
1d700 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  N] [file control
1d710 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ].** </ul>.*/.in
1d720 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1d730 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1d740 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d750 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1d760 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1d770 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ry.** METHOD: sq
1d780 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1d790 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1d7a0 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
1d7b0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1d7c0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
1d7d0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
1d7e0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
1d7f0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
1d800 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
1d810 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
1d820 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
1d830 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
1d840 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
1d850 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
1d860 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
1d870 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
1d880 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
1d890 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
1d8a0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
1d8b0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1d8c0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
1d8d0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
1d8e0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
1d8f0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
1d900 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
1d910 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1d920 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
1d930 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
1d940 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1d950 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1d960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
1d970 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
1d980 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
1d990 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
1d9a0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
1d9b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
1d9c0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1d9d0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
1d9e0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
1d9f0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
1da00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
1da10 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
1da20 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
1da30 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
1da40 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
1da50 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
1da60 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
1da70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
1da80 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
1da90 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
1daa0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
1dab0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1dac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
1dad0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
1dae0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
1daf0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1db00 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
1db10 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
1db20 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1db30 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
1db40 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
1db50 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
1db60 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
1db70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
1db80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1db90 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
1dba0 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
1dbb0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1dbc0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1dbd0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
1dbe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
1dbf0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
1dc00 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1dc10 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1dc20 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1dc30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1dc40 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
1dc50 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
1dc60 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
1dc70 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
1dc80 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
1dc90 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
1dca0 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
1dcb0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1dcc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1dcd0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
1dce0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1dcf0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1dd00 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
1dd10 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
1dd20 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
1dd30 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
1dd40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1dd50 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
1dd60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1dd70 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
1dd80 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
1dd90 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
1dda0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1ddb0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
1ddc0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
1ddd0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
1dde0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1ddf0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1de00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1de10 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
1de20 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ns..*/.void sqli
1de30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1de40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1de50 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1de60 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1de70 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1de80 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1de90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1dea0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1deb0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1dec0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1ded0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1dee0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1def0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1df00 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1df10 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1df20 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1df30 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1df40 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1df50 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1df60 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1df70 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1df80 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1df90 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1dfa0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1dfb0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1dfc0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1dfd0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1dfe0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1dff0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1e000 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1e010 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1e020 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1e030 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1e040 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1e050 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1e060 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1e070 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1e080 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1e090 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1e0a0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1e0b0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1e0c0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1e0d0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1e0e0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1e0f0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1e100 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1e110 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1e120 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1e130 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1e140 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1e150 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1e160 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1e170 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1e180 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1e190 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1e1a0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1e1b0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1e1c0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1e1d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e1e0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1e1f0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1e200 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1e210 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1e220 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1e230 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1e240 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1e250 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1e260 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1e270 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1e280 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1e290 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1e2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1e2b0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1e2c0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1e2d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e2e0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1e2f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1e300 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1e310 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1e320 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1e330 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1e340 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1e350 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1e360 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1e370 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1e380 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1e390 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1e3a0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1e3b0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1e3c0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1e3d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1e3e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1e3f0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1e400 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1e410 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1e420 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1e430 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1e440 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1e450 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1e460 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1e470 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1e480 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e490 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e4a0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1e4b0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1e4c0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e4d0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1e4e0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1e4f0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1e500 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1e510 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1e520 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1e530 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1e540 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1e550 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1e560 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1e570 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e580 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1e590 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1e5a0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1e5b0 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1e5c0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1e5d0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1e5e0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1e5f0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1e600 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1e610 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1e620 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1e630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e640 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1e650 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1e660 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1e670 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1e680 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1e690 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1e6a0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1e6b0 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1e6c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1e6d0 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1e6e0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1e6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1e700 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1e710 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1e720 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1e730 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1e740 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1e750 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1e760 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1e770 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1e780 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1e790 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1e7a0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1e7b0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1e7c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1e7d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1e7e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1e7f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1e800 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1e810 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1e820 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1e830 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e840 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1e850 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1e860 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1e870 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1e880 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1e890 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1e8a0 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1e8b0 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1e8c0 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1e8d0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1e8e0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1e8f0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1e900 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1e910 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1e920 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1e930 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1e940 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1e950 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1e960 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1e970 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1e980 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1e990 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1e9a0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1e9b0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1e9c0 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1e9d0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1e9e0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1e9f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1ea00 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1ea10 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1ea20 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1ea30 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1ea40 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1ea50 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1ea60 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1ea70 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1ea80 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1ea90 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1eaa0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1eab0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1eac0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1ead0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1eae0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1eaf0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1eb00 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1eb10 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1eb20 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1eb30 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1eb40 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1eb50 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1eb60 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1eb70 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1eb80 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1eb90 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1eba0 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1ebb0 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1ebc0 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1ebd0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1ebe0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1ebf0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1ec00 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1ec10 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1ec20 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1ec30 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1ec40 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1ec50 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1ec60 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1ec70 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1ec80 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1ec90 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1eca0 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1ecb0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ecc0 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1ecd0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1ece0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1ecf0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1ed00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1ed10 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1ed20 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1ed30 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1ed40 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1ed50 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1ed60 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1ed70 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1ed80 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1ed90 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1eda0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1edb0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1edc0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1edd0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1ede0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1edf0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1ee00 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1ee10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ee20 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1ee30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1ee40 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1ee50 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1ee60 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1ee70 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1ee80 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1ee90 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1eea0 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1eeb0 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1eec0 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1eed0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1eee0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1eef0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1ef00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1ef10 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1ef20 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1ef30 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1ef40 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1ef50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1ef60 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1ef70 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1ef80 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1ef90 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1efa0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1efb0 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1efc0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1efd0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1efe0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1eff0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1f000 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1f010 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1f020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1f030 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1f040 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1f050 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1f060 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1f070 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1f080 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1f090 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1f0a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f0b0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1f0c0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1f0d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1f0e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1f0f0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1f100 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1f110 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1f120 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1f130 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1f140 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1f150 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1f160 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1f170 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1f180 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1f190 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1f1a0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1f1b0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1f1c0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1f1d0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1f1e0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1f1f0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1f200 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1f210 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1f220 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1f230 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1f240 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1f250 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1f260 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1f270 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1f280 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1f290 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1f2a0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1f2b0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1f2c0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1f2d0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1f2e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1f2f0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1f300 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f310 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1f320 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1f330 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1f340 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1f350 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1f360 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1f370 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1f380 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1f390 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1f3a0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1f3b0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1f3c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1f3d0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1f3e0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1f3f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1f400 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1f410 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1f420 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1f430 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1f440 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1f450 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1f460 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1f470 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1f480 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1f490 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1f4a0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1f4b0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1f4c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1f4d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1f4e0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1f4f0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1f500 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1f510 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1f520 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1f530 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1f540 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1f550 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1f560 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1f570 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1f580 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1f590 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1f5a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1f5b0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1f5c0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1f5d0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1f5e0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1f5f0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1f600 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1f610 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1f620 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1f630 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1f640 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1f650 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1f660 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1f670 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1f680 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1f690 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1f6a0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1f6b0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1f6c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1f6d0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1f6e0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1f6f0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1f700 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1f710 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1f720 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1f730 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1f740 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1f750 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1f760 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1f770 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1f780 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1f790 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1f7a0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1f7b0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1f7c0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1f7d0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1f7e0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1f7f0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1f800 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1f810 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1f820 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1f830 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1f840 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1f850 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1f860 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1f870 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1f880 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1f890 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1f8a0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1f8b0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1f8c0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1f8d0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1f8e0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1f8f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f900 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1f910 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1f920 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1f930 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1f940 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1f950 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1f960 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1f970 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1f980 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1f990 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1f9a0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1f9b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1f9c0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1f9d0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1f9e0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1f9f0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1fa00 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1fa10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1fa20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1fa30 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1fa40 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1fa50 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1fa60 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1fa70 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1fa80 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1fa90 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1faa0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1fab0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1fac0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1fad0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1fae0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1faf0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1fb00 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1fb10 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1fb20 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1fb30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1fb40 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1fb50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1fb60 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1fb70 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1fb80 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1fb90 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1fba0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1fbb0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1fbc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1fbd0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1fbe0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1fbf0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1fc00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1fc10 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1fc20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1fc30 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1fc40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1fc50 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1fc60 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1fc70 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1fc80 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1fc90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1fca0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1fcb0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1fcc0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1fcd0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1fce0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1fcf0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1fd00 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1fd10 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1fd20 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1fd30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1fd40 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1fd50 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1fd60 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1fd70 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1fd80 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1fd90 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1fda0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1fdb0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1fdc0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1fdd0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1fde0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1fdf0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1fe00 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fe10 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1fe20 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1fe30 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1fe40 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1fe50 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1fe60 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1fe70 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1fe80 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1fe90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1fea0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1feb0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1fec0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1fed0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1fee0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1fef0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1ff00 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1ff10 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1ff20 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1ff30 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1ff40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ff50 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1ff60 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1ff70 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1ff80 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1ff90 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1ffa0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1ffb0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1ffc0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1ffd0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1ffe0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1fff0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
20000 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
20010 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
20020 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
20030 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
20040 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
20050 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
20060 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20070 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
20080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
20090 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
200a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
200b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
200c0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
200d0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
200e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
200f0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
20100 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
20110 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
20120 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
20130 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
20140 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
20150 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
20160 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
20170 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
20180 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
20190 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
201a0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
201b0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
201c0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
201d0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
201e0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
201f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
20200 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
20210 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
20220 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
20230 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
20240 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
20250 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
20260 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20270 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
20280 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
20290 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
202a0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
202b0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
202c0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
202d0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
202e0 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
202f0 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74  he common format
20300 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
20310 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
20320 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66  d library printf
20330 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  () .** plus some
20340 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
20350 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
20360 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25   ([%q], [%Q], [%
20370 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a  w], and [%z])..*
20380 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74  * See the [built
20390 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f  -in printf()] do
203a0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
203b0 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  details..**.** ^
203c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
203d0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
203e0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
203f0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
20400 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
20410 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
20420 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
20430 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20  malloc64()]..** 
20440 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
20450 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
20460 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
20470 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
20480 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
20490 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
204a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
204b0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
204c0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
204d0 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  c64()] is unable
204e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
204f0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
20500 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
20510 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
20520 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
20530 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
20540 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
20550 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
20560 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
20570 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
20580 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
20590 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
205a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
205b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
205c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
205d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
205e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
205f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
20600 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
20610 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
20620 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
20630 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
20640 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
20650 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
20660 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
20670 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
20680 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
20690 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
206a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
206b0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
206c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
206d0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
206e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
206f0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
20700 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
20710 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
20720 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
20730 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
20740 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
20750 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
20760 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
20770 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
20780 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
20790 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
207a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
207b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
207c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
207d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
207e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
207f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
20800 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
20810 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
20820 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
20830 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
20840 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
20850 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
20860 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
20870 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
20880 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
20890 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
208a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
208b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
208c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
208d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
208e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
208f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
20900 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
20910 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
20920 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
20930 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
20940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20950 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
20960 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
20970 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
20980 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20990 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
209a0 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  o:  [built-in pr
209b0 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66  intf()], [printf
209c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
209d0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
209e0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
209f0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
20a00 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
20a10 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
20a20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
20a30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
20a40 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
20a50 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
20a60 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
20a70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20a80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
20a90 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
20aa0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
20ab0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
20ac0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
20ad0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
20ae0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
20af0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
20b00 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
20b10 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
20b20 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
20b30 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
20b40 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
20b50 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
20b60 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
20b70 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
20b80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
20b90 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
20ba0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
20bb0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
20bc0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
20bd0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
20be0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
20bf0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
20c00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
20c10 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
20c20 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
20c30 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
20c40 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20c50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
20c60 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20c70 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
20c80 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
20c90 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
20ca0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
20cb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
20cc0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20cd0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
20ce0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
20cf0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
20d00 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
20d10 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
20d20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
20d30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20d40 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
20d50 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
20d60 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
20d70 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
20d80 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
20d90 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
20da0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
20db0 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
20dc0 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
20dd0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
20de0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
20df0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
20e00 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
20e10 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
20e20 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
20e30 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
20e40 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
20e50 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
20e60 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
20e70 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
20e80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
20e90 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
20ea0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
20eb0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
20ec0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
20ed0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
20ee0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
20ef0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
20f00 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
20f10 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
20f20 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
20f30 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
20f40 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
20f50 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
20f60 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
20f70 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
20f80 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
20f90 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
20fa0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
20fb0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
20fc0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
20fd0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
20fe0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
20ff0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
21000 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
21010 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
21020 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
21030 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
21040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21050 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
21060 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
21070 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
21080 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
21090 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
210a0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
210b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
210c0 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
210d0 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
210e0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
210f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
21100 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
21110 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21120 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
21130 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
21140 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
21150 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
21160 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
21170 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21180 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
21190 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
211a0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
211b0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
211c0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
211d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
211e0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
211f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21200 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
21210 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
21220 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
21230 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
21240 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
21250 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
21260 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
21270 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
21280 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
21290 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
212a0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
212b0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
212c0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
212d0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
212e0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
212f0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
21300 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
21310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
21320 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
21330 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
21340 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
21350 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21360 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
21370 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
21380 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
21390 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
213a0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
213b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
213c0 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
213d0 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
213e0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
213f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21400 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
21410 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
21420 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
21430 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
21440 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
21450 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
21460 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
21470 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
21480 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
21490 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
214a0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
214b0 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
214c0 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
214d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
214e0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
214f0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
21500 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
21510 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
21520 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
21530 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
21540 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
21550 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
21560 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
21570 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
21580 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
21590 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
215a0 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
215b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
215c0 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
215d0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
215e0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
215f0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
21600 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
21610 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
21620 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
21630 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
21640 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
21650 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
21660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
21670 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
21680 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
21690 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
216a0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
216b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
216c0 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
216d0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
216e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
216f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
21700 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
21710 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
21720 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
21730 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
21740 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
21750 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
21760 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
21770 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
21780 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
21790 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
217a0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
217b0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
217c0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
217d0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
217e0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
217f0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
21800 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
21810 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
21820 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
21830 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
21840 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
21850 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
21860 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
21870 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
21880 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
21890 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
218a0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
218b0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
218c0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
218d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
218e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
218f0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
21900 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
21910 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
21920 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
21930 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
21940 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
21950 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
21960 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
21970 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
21980 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
21990 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
219a0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
219b0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
219c0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
219d0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
219e0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
219f0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
21a00 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
21a10 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
21a20 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
21a30 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
21a40 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
21a50 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
21a60 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
21a70 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
21a80 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21a90 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21aa0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
21ab0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
21ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
21ad0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
21ae0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
21af0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
21b00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
21b10 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
21b20 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
21b30 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
21b40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21b50 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
21b60 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
21b70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
21b80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
21b90 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
21ba0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
21bb0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
21bc0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
21bd0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
21be0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21bf0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
21c00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
21c10 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
21c20 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
21c30 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
21c40 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
21c50 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
21c60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
21c70 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
21c80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
21c90 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
21ca0 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
21cb0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
21cc0 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
21cd0 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
21ce0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
21cf0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
21d00 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
21d10 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
21d20 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
21d30 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
21d40 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
21d50 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
21d60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
21d70 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
21d80 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
21d90 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
21da0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
21db0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
21dc0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
21dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
21de0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
21df0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
21e00 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
21e10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
21e20 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
21e30 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
21e40 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
21e50 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
21e60 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
21e70 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
21e80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
21e90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
21ea0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
21eb0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
21ec0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
21ed0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
21ee0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
21ef0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
21f00 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
21f10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
21f20 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
21f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
21f40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
21f50 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
21f60 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
21f70 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
21f80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
21f90 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
21fa0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
21fb0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
21fc0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
21fd0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
21fe0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
21ff0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
22000 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
22010 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
22020 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
22030 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
22040 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
22050 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
22060 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22070 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
22080 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
22090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
220a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
220b0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
220c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
220d0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
220e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
220f0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
22100 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
22110 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
22120 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
22130 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
22140 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
22150 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
22160 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22170 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
22180 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
22190 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
221a0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
221b0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
221c0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
221d0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
221e0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
221f0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
22200 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
22210 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
22220 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
22230 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
22240 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
22250 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
22260 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
22270 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
22280 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
22290 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
222a0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
222b0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
222c0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
222d0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
222e0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
222f0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
22300 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
22310 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
22320 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
22330 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
22340 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
22350 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
22360 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
22370 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
22380 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
22390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
223a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
223b0 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
223c0 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
223d0 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
223e0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
223f0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
22400 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
22410 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
22420 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
22430 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
22440 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
22450 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
22460 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
22470 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
22480 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22490 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
224a0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
224b0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
224c0 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
224d0 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
224e0 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
224f0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
22500 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
22510 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
22520 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
22530 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
22540 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
22550 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
22560 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
22570 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
22580 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
22590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
225a0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
225b0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
225c0 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
225d0 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
225e0 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
225f0 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
22600 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
22610 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
22620 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
22630 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
22640 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
22650 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
22660 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
22670 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
22680 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22690 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
226a0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
226b0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
226c0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
226d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
226e0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
226f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22700 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
22710 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
22720 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
22730 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
22740 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22750 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
22760 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
22770 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
22780 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
22790 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
227a0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
227b0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
227c0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
227d0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
227e0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
227f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
22800 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
22810 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
22820 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
22830 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
22840 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
22850 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
22860 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
22870 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
22880 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
22890 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
228a0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
228b0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
228c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
228d0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
228e0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
228f0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
22900 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
22910 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
22920 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
22930 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
22940 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
22950 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
22960 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
22970 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
22980 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
22990 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
229a0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
229b0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
229c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
229d0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
229e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
229f0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
22a00 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
22a10 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
22a20 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
22a30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22a40 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
22a50 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
22a60 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
22a70 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
22a80 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
22a90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
22aa0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
22ab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22ac0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
22ad0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
22ae0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
22af0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
22b00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
22b10 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
22b20 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
22b30 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
22b40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
22b50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22b60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22b70 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
22b80 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
22b90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22ba0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22bb0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
22bc0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
22bd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
22be0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
22bf0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
22c00 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
22c10 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
22c20 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
22c30 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
22c40 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
22c50 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
22c60 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
22c70 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
22c80 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
22c90 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
22ca0 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
22cb0 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
22cc0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
22cd0 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
22ce0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
22cf0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
22d00 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
22d10 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
22d20 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
22d30 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
22d40 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
22d50 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
22d60 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
22d70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
22d80 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
22d90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
22da0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
22db0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
22dc0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
22dd0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
22de0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
22df0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
22e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22e10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
22e20 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
22e30 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
22e40 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
22e50 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
22e60 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
22e70 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
22e80 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
22e90 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
22ea0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
22eb0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
22ec0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
22ed0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
22ee0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
22ef0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
22f00 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
22f10 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
22f20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
22f30 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
22f40 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
22f50 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
22f60 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
22f70 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
22f80 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
22f90 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
22fa0 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
22fb0 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
22fc0 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
22fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
22fe0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
22ff0 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
23000 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
23010 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
23020 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
23030 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
23040 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
23050 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
23060 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
23070 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
23080 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
23090 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
230a0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
230b0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
230c0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
230d0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
230e0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
230f0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
23100 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
23110 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
23120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
23130 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
23140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
23150 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
23160 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
23170 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
23180 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
23190 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
231a0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
231b0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
231c0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
231d0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
231e0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
231f0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
23200 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
23210 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
23220 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
23230 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
23240 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
23250 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
23260 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
23270 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
23280 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
23290 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
232a0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
232b0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
232c0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
232d0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
232e0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
232f0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
23300 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
23310 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
23320 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
23330 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
23340 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
23350 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
23360 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
23370 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
23380 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
23390 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
233a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
233b0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
233c0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
233d0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
233e0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
233f0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
23400 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
23410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
23420 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
23430 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
23440 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
23450 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
23460 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
23470 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
23480 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
23490 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
234a0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
234b0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
234c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
234d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
234e0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
234f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
23500 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
23510 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
23520 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
23530 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
23540 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
23550 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
23560 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
23570 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
23580 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
23590 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
235a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
235b0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
235c0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
235d0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
235e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
235f0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
23600 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23610 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
23620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23630 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
23640 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
23650 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
23660 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
23670 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
23680 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
23690 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
236a0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
236b0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
236c0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
236d0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
236e0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
236f0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
23700 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
23710 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
23720 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
23730 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
23740 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
23750 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
23760 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
23770 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
23780 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23790 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
237a0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
237b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
237c0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
237d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
237e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
237f0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
23800 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
23810 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
23820 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
23830 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
23840 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
23850 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
23860 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
23870 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
23880 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
23890 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
238a0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
238b0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
238c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
238d0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
238e0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
238f0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
23900 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
23910 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23920 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
23930 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
23940 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
23950 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
23960 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
23970 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
23980 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
23990 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
239a0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
239b0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
239c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
239d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
239e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
239f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
23a00 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
23a10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
23a20 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
23a30 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
23a40 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
23a50 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
23a60 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
23a70 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
23a80 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
23a90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
23aa0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
23ab0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
23ac0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
23ad0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
23ae0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
23af0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
23b00 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
23b10 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
23b20 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
23b30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
23b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
23b50 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
23b60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
23b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
23b80 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
23b90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
23ba0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
23bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23bc0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
23bd0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
23be0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
23bf0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
23c00 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
23c10 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
23c20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
23c30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
23c40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
23c50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
23c60 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
23c70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
23c80 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
23c90 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
23ca0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
23cb0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
23cc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
23cd0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
23ce0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
23cf0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
23d00 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
23d10 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
23d20 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
23d30 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
23d40 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
23d50 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
23d60 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
23d70 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
23d80 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
23d90 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
23da0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
23db0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
23dc0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
23dd0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
23de0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
23df0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
23e00 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
23e10 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
23e20 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
23e30 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
23e40 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
23e50 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
23e60 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
23e70 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
23e80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
23e90 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
23ea0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
23eb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
23ec0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
23ed0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
23ee0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
23ef0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
23f00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
23f10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23f20 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
23f30 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
23f40 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
23f50 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
23f60 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
23f70 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
23f80 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
23f90 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
23fa0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
23fb0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
23fc0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
23fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23fe0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23ff0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
24000 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
24010 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
24020 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
24030 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
24040 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24050 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24060 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24070 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
24080 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
24090 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
240a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
240b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
240c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
240d0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
240e0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
240f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24100 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24110 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24120 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
24130 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24140 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24150 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24160 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24170 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
24180 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
24190 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
241a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
241b0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
241c0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
241d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
241e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
241f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24200 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
24210 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
24220 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24230 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24240 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24250 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
24260 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
24270 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24280 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
242a0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
242b0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
242c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
242d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
242e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
242f0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
24300 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
24310 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
24320 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
24340 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
24350 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
24360 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24370 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24390 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
243a0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
243b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
243c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
243d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
243e0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
243f0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
24400 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24410 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24420 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
24430 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
24440 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
24450 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
24460 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
24470 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
24480 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
24490 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
244a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
244b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
244c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
244d0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
244e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
244f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
24500 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24510 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
24520 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
24530 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
24540 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24550 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24560 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
24570 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
24580 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24590 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
245a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
245b0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
245c0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
245d0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
245e0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
245f0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
24600 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
24610 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
24620 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24630 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
24640 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24650 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
24660 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
24670 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24680 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24690 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
246a0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
246b0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
246c0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
246d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
246e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
246f0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
24700 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
24710 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
24720 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
24730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24740 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
24750 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
24760 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
24770 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24790 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
247a0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
247b0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
247c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
247d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
247e0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
247f0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
24800 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
24810 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
24830 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
24840 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
24850 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24860 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
24880 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
24890 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
248a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
248b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
248c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
248d0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
248e0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
248f0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
24900 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
24910 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
24920 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
24930 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
24940 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
24950 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
24960 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
24970 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
24980 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
24990 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
249a0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
249b0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
249c0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
249d0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
249e0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
249f0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
24a00 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
24a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
24a20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
24a30 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
24a40 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
24a50 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
24a60 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
24a70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24a80 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
24a90 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
24aa0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
24ab0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
24ac0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24ad0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
24ae0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
24af0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
24b00 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
24b10 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
24b20 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
24b30 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
24b40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24b50 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
24b60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
24b70 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
24b80 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
24b90 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
24ba0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
24bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
24bc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
24bd0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
24be0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
24bf0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
24c00 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
24c10 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
24c20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24c30 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
24c40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24c50 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
24c60 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
24c70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24c80 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
24c90 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
24ca0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
24cb0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
24cc0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
24cd0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
24ce0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
24cf0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
24d00 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
24d10 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
24d20 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
24d30 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
24d40 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
24d50 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
24d60 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
24d70 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
24d80 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
24d90 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
24da0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
24db0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
24dc0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
24dd0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
24de0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
24df0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
24e00 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
24e10 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
24e20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
24e30 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
24e40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
24e50 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
24e60 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
24e70 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
24e80 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
24e90 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
24ea0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
24eb0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
24ec0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
24ed0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
24ee0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
24ef0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
24f00 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
24f10 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
24f20 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
24f30 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
24f40 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
24f50 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
24f60 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
24f70 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
24f80 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
24f90 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
24fa0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
24fb0 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
24fc0 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
24fd0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
24fe0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
24ff0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
25000 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25010 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
25020 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
25030 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
25040 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
25050 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a  ck.  Invoking.**
25060 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25070 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71  _trace()] or [sq
25080 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25090 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68  ] will cancel th
250a0 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c  e.** profile cal
250b0 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45  lback..*/.SQLITE
250c0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
250d0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
250e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
250f0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
25100 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
25110 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  oid*);.SQLITE_DE
25120 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
25130 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
25140 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
25150 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
25160 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
25170 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
25180 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
25190 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
251a0 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a  e Event Codes.**
251b0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
251c0 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68  E_TRACE.**.** Th
251d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64  ese constants id
251e0 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f  entify classes o
251f0 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61  f events that ca
25200 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a  n be monitored.*
25210 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  * using the [sql
25220 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
25230 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20   tracing logic. 
25240 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a   The M argument.
25250 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
25260 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
25270 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f  ] is an OR-ed co
25280 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65  mbination of one
25290 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74   or more of.** t
252a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
252b0 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69  stants.  ^The fi
252c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
252d0 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
252e0 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20  ck.** is one of 
252f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
25300 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e  nstants..**.** N
25310 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74  ew tracing const
25320 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65  ants may be adde
25330 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
25340 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  ases..**.** ^A t
25350 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61  race callback ha
25360 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  s four arguments
25370 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  : xCallback(T,C,
25380 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
25390 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
253a0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74  of the integer t
253b0 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e  ype codes above.
253c0 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
253d0 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
253e0 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
253f0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61  nter passed in a
25400 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
25410 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
25420 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
25430 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
25440 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
25450 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
25460 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
25470 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a   T..**.** <dl>.*
25480 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
25490 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49  _STMT]] <dt>SQLI
254a0 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64  TE_TRACE_STMT</d
254b0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
254c0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
254d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
254e0 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61  ked when a prepa
254f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
25500 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75   first begins ru
25510 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62  nning and possib
25520 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65  ly at other time
25530 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  s during the.** 
25540 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
25550 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25560 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20  ent, such as at 
25570 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63  the start of eac
25580 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62  h.** trigger sub
25590 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20  program. ^The P 
255a0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
255b0 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
255c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
255d0 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67  ent]. ^The X arg
255e0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
255f0 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  er to a string w
25600 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75  hich.** is the u
25610 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65  nexpanded SQL te
25620 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
25630 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
25640 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a  an SQL comment .
25650 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
25660 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e  s the invocation
25670 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
25680 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ^The callback ca
25690 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65  n compute.** the
256a0 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20   same text that 
256b0 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20  would have been 
256c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
256d0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
256e0 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  trace()].** inte
256f0 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74  rface by using t
25700 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68  he X argument wh
25710 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68  en X begins with
25720 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69   "--" and invoki
25730 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
25740 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20  xpanded_sql(P)] 
25750 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
25760 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
25770 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51  PROFILE]] <dt>SQ
25780 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
25790 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  LE</dt>.** <dd>^
257a0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
257b0 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
257c0 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78   provides approx
257d0 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65  imately the same
257e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
257f0 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  as is provided b
25800 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  y the [sqlite3_p
25810 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61  rofile()] callba
25820 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  ck..** ^The P ar
25830 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
25840 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
25850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25860 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
25870 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
25880 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
25890 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73   which is the es
258a0 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68  timated of.** th
258b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
258c0 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20  second that the 
258d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
258e0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
258f0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54  ** ^The SQLITE_T
25900 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
25910 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
25920 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   when the statem
25930 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
25940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
25950 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c  CE_ROW]] <dt>SQL
25960 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64  ITE_TRACE_ROW</d
25970 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
25980 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63  LITE_TRACE_ROW c
25990 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
259a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72  ed whenever a pr
259b0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
259c0 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20  ent generates a 
259d0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65  single row of re
259e0 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20  sult.  .** ^The 
259f0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
25a00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
25a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25a20 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
25a30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
25a40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  sed..**.** [[SQL
25a50 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d  ITE_TRACE_CLOSE]
25a60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
25a70 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  CE_CLOSE</dt>.**
25a80 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
25a90 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c  TRACE_CLOSE call
25aa0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
25ab0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a  when a database.
25ac0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  ** connection cl
25ad0 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  oses..** ^The P 
25ae0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
25af0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
25b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25b10 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  n] object.** and
25b20 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
25b30 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f  is unused..** </
25b40 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
25b50 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
25b60 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
25b70 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
25b80 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32  _PROFILE    0x02
25b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25ba0 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20  TRACE_ROW       
25bb0 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51   0x04.#define SQ
25bc0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25bd0 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a        0x08../*.*
25be0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
25bf0 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45  Trace Hook.** ME
25c00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
25c10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25c20 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
25c30 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  P) interface reg
25c40 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63  isters a trace c
25c50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
25c60 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64  ion X against [d
25c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25c80 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f  on] D, using pro
25c90 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20  perty mask M.** 
25ca0 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  and context poin
25cb0 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20  ter P.  ^If the 
25cc0 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  X callback is.**
25cd0 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20   NULL or if the 
25ce0 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20  M mask is zero, 
25cf0 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20  then tracing is 
25d00 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a  disabled.  The.*
25d10 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  * M argument sho
25d20 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69  uld be the bitwi
25d30 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  se OR-ed combina
25d40 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20  tion of.** zero 
25d50 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f  or more [SQLITE_
25d60 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73  TRACE] constants
25d70 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61  ..**.** ^Each ca
25d80 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c  ll to either sql
25d90 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
25da0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25db0 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a  () overrides .**
25dc0 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70   (cancels) any p
25dd0 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
25de0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
25df0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
25e00 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  2()..**.** ^The 
25e10 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  X callback is in
25e20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
25e30 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73  ny of the events
25e40 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a   identified by .
25e50 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e  ** mask M occur.
25e60 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72    ^The integer r
25e70 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
25e80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
25e90 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67   currently.** ig
25ea0 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68  nored, though th
25eb0 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e  is may change in
25ec0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
25ed0 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  .  Callback.** i
25ee0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
25ef0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72  hould return zer
25f00 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75  o to ensure futu
25f10 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  re compatibility
25f20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
25f30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25f40 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61  oked with four a
25f50 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61  rguments: callba
25f60 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
25f70 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
25f80 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53  is one of the [S
25f90 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20  QLITE_TRACE].** 
25fa0 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64  constants to ind
25fb0 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61  icate why the ca
25fc0 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b  llback was invok
25fd0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ed..** ^The C ar
25fe0 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
25ff0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
26000 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20  pointer..** The 
26010 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
26020 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
26030 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
26040 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
26050 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61   The sqlite3_tra
26060 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  ce_v2() interfac
26070 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  e is intended to
26080 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67   replace the leg
26090 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
260a0 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  s [sqlite3_trace
260b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
260c0 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74  _profile()], bot
260d0 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72  h of which.** ar
260e0 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f  e deprecated..*/
260f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
26100 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
26110 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
26120 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
26130 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
26140 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
26150 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
26160 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26170 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
26180 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
26190 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
261a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
261b0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
261c0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
261d0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
261e0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
261f0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
26200 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
26210 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
26220 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
26230 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
26240 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
26250 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
26260 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
26270 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
26280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
26290 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
262a0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
262b0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
262c0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
262d0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
262e0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
262f0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
26300 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
26310 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
26320 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
26330 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
26340 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
26350 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
26360 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
26370 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
26380 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
26390 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
263a0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
263b0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
263c0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
263d0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
263e0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
263f0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
26400 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
26410 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
26420 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
26430 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
26440 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
26450 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
26460 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
26470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
26480 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
26490 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
264a0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
264b0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
264c0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
264d0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
264e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
264f0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
26500 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
26510 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
26520 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
26530 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
26540 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
26550 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
26560 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
26570 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
26580 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
26590 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
265a0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
265b0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
265c0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
265d0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
265e0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
265f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
26600 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
26610 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
26620 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
26630 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
26640 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26650 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
26660 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
26670 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
26680 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
26690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
266a0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
266b0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
266c0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
266d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
266e0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
266f0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
26700 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
26710 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
26720 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
26730 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
26740 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
26750 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
26760 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
26770 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
26780 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
26790 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
267a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
267b0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
267c0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
267d0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
267e0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
267f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
26800 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
26810 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
26820 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
26830 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
26840 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
26850 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
26860 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
26870 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
26880 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
26890 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
268a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
268b0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
268c0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
268d0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
268e0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
268f0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
26900 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
26910 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
26920 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
26930 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
26940 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
26950 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
26960 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
26970 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
26980 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
26990 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
269a0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
269b0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
269c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
269d0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
269e0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
269f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
26a00 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
26a10 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
26a20 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
26a30 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
26a40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
26a50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
26a60 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
26a70 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
26a80 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
26a90 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
26aa0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
26ab0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
26ac0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
26ad0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
26ae0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
26af0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
26b00 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
26b10 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
26b20 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
26b30 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
26b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26b50 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
26b60 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
26b70 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
26b80 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
26b90 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
26ba0 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
26bb0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
26bc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
26bd0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
26be0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
26bf0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
26c00 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
26c10 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
26c20 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
26c30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26c40 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
26c50 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
26c60 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
26c70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
26c80 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
26c90 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
26ca0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
26cb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26cc0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
26cd0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
26ce0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
26cf0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
26d00 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
26d10 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
26d20 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
26d30 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
26d40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26d50 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
26d60 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
26d70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26d80 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
26d90 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
26da0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
26db0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
26dc0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
26dd0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
26de0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
26df0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
26e00 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
26e10 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
26e20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
26e30 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
26e40 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
26e50 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
26e60 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
26e70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
26e80 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
26e90 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
26ea0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
26eb0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
26ec0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
26ed0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
26ee0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
26ef0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
26f00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
26f10 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
26f20 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
26f30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
26f40 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
26f50 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
26f60 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
26f70 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
26f80 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
26f90 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
26fa0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
26fb0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
26fc0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
26fd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
26fe0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
26ff0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
27000 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27010 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
27020 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
27030 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
27040 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
27050 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
27060 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
27070 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
27080 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
27090 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
270a0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
270b0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
270c0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
270d0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
270e0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
270f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27100 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
27110 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
27120 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
27130 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
27140 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27150 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
27160 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
27170 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
27180 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
27190 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
271a0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
271b0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
271c0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
271d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
271e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
271f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
27200 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27210 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
27220 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
27230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27240 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
27250 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
27260 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
27270 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
27280 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
27290 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
272a0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
272b0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
272c0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
272d0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
272e0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
272f0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
27300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27310 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
27320 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
27330 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
27340 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
27350 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
27360 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
27370 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
27380 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
27390 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
273a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
273b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
273c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
273d0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
273e0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
273f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
27400 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
27410 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27420 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
27430 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
27440 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
27450 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
27460 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
27470 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
27480 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
27490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
274a0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
274b0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
274c0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
274d0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
274e0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
274f0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
27500 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27510 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27520 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
27540 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
27550 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
27560 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
27570 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
27580 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
27590 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
275a0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
275b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
275c0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
275d0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
275e0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
275f0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
27600 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
27610 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
27620 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
27630 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
27640 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
27650 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
27660 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
27670 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
27680 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
27690 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
276a0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
276b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
276c0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
276d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
276e0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
276f0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
27700 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
27710 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
27720 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
27730 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
27740 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
27750 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
27760 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
27770 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
27780 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
27790 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
277a0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
277b0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
277c0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
277d0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
277e0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
277f0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
27800 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
27810 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
27820 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
27830 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
27840 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
27850 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
27860 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
27870 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
27880 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
27890 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
278a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
278b0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
278c0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
278d0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
278e0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
278f0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
27900 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
27910 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
27920 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
27930 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
27940 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
27950 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
27960 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
27970 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
27980 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
27990 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
279a0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
279b0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
279c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
279d0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
279e0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
279f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27a00 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
27a10 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
27a20 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
27a30 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
27a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
27a50 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
27a60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
27a70 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
27a80 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
27a90 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
27aa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
27ab0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
27ac0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
27ad0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
27ae0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
27af0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
27b00 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
27b10 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
27b20 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
27b30 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
27b40 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
27b50 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
27b60 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
27b70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
27b80 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
27b90 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
27ba0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
27bb0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
27bc0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
27bd0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
27be0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
27bf0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
27c00 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
27c10 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
27c20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
27c30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
27c40 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
27c50 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
27c60 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
27c70 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
27c80 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
27c90 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
27ca0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
27cb0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
27cc0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
27cd0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
27ce0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
27cf0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
27d00 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
27d10 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
27d20 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
27d30 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
27d40 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
27d50 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
27d60 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
27d70 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
27d80 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
27d90 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
27da0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
27db0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
27dc0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
27dd0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
27de0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
27df0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
27e00 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
27e10 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
27e20 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
27e30 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
27e40 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
27e50 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
27e60 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
27e70 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
27e80 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
27e90 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
27ea0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
27eb0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
27ec0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
27ed0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
27ee0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
27ef0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
27f00 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
27f10 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
27f20 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
27f30 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
27f40 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
27f50 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
27f60 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
27f70 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
27f80 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
27f90 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
27fa0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
27fb0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
27fc0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
27fd0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
27fe0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
27ff0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
28000 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
28010 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
28020 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
28030 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
28040 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
28050 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
28060 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
28070 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
28080 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
28090 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
280a0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
280b0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
280c0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
280d0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
280e0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
280f0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
28100 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
28110 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
28120 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
28130 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
28140 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
28150 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
28160 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
28170 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
28180 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28190 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
281a0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
281b0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
281c0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
281d0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
281e0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
281f0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
28200 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
28210 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
28220 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
28230 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
28240 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
28250 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
28260 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
28270 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
28280 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
28290 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
282a0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
282b0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
282c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
282d0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
282e0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
282f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
28300 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
28310 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
28320 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
28330 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
28340 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
28350 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
28360 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
28370 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
28380 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
28390 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
283a0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
283b0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
283c0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
283d0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
283e0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
283f0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28400 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
28410 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
28420 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
28430 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
28440 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
28450 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
28460 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
28470 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
28480 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
28490 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
284a0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
284b0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
284c0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
284d0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
284e0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
284f0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
28500 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
28510 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
28520 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
28530 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
28540 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
28550 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
28560 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
28570 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
28580 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
28590 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
285a0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
285b0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
285c0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
285d0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
285e0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
285f0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
28600 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
28610 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
28620 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
28630 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
28640 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
28650 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
28660 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
28670 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
28680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
28690 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
286a0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
286b0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
286c0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
286d0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
286e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
286f0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
28700 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
28710 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
28720 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
28730 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
28740 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
28750 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
28760 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
28770 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
28780 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
28790 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
287a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
287b0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
287c0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
287d0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
287e0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
287f0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
28800 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
28810 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
28820 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
28830 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
28840 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
28850 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
28860 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28870 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
28880 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
28890 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
288a0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
288b0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
288c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
288d0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
288e0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
288f0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
28900 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
28910 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
28920 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
28930 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
28940 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
28950 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
28960 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
28970 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
28980 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
28990 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
289a0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
289b0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
289c0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
289d0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
289e0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
289f0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
28a00 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
28a10 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
28a20 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
28a30 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
28a40 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
28a50 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
28a60 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
28a70 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
28a80 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28a90 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
28aa0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
28ab0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
28ac0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
28ad0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
28ae0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
28af0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
28b00 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
28b10 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
28b20 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
28b30 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
28b40 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
28b50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
28b60 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
28b70 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
28b80 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
28b90 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
28ba0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
28bb0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
28bc0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
28bd0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
28be0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
28bf0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
28c00 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
28c10 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
28c20 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
28c30 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
28c40 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
28c50 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
28c60 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
28c70 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
28c80 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
28c90 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
28ca0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
28cb0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
28cc0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
28cd0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
28ce0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
28cf0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
28d00 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
28d10 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
28d20 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
28d30 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
28d40 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
28d50 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
28d60 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
28d70 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28d80 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
28d90 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
28da0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
28db0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
28dc0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
28dd0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
28de0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
28df0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
28e00 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
28e10 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
28e20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
28e30 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
28e40 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
28e50 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
28e60 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
28e70 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
28e80 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
28e90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28ea0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
28eb0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
28ec0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
28ed0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
28ee0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
28ef0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
28f00 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
28f10 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
28f20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
28f30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28f40 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
28f50 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
28f60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28f70 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
28f80 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
28f90 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
28fa0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
28fb0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
28fc0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
28fd0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
28fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
28ff0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
29000 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
29010 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
29020 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
29030 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
29040 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
29050 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
29060 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
29070 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
29080 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
29090 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
290a0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
290b0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
290c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
290d0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
290e0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
290f0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
29100 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
29110 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
29120 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
29130 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
29140 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
29150 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
29160 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
29170 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
29180 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
29190 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
291a0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
291b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
291c0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
291d0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
291e0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
291f0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
29200 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
29210 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
29220 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
29230 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
29240 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
29250 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
29260 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
29270 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
29280 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
29290 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
292a0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
292b0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
292c0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
292d0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
292e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
292f0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
29300 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
29310 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
29320 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
29330 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
29340 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
29350 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
29360 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
29370 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
29380 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
29390 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
293a0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
293b0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
293c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
293d0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
293e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
293f0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
29400 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
29410 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
29420 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
29430 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
29440 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
29450 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
29460 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
29470 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
29480 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
29490 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
294a0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
294b0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
294c0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
294d0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
294e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
294f0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
29500 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
29510 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
29520 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
29530 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
29540 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
29550 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
29560 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
29570 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
29580 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
29590 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
295a0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
295b0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
295c0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
295d0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
295e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
295f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
29600 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
29610 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
29620 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
29630 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
29640 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
29650 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
29660 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
29670 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
29680 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
29690 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
296a0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
296b0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
296c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
296d0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
296e0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
296f0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
29700 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
29710 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
29720 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
29730 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
29740 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
29750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
29760 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
29770 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
29780 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
29790 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
297a0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
297b0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
297c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
297d0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
297e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
297f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
29800 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
29810 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
29820 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
29830 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
29840 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
29850 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
29860 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
29870 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
29880 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
29890 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
298a0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
298b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
298c0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
298d0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
298e0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
298f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29900 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
29910 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
29920 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
29930 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
29940 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
29950 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
29960 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
29970 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
29980 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
29990 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
299a0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
299b0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
299c0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
299d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
299e0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
299f0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
29a00 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
29a10 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
29a20 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
29a30 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
29a40 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
29a50 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
29a60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
29a70 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
29a80 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
29a90 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
29aa0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
29ab0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
29ac0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
29ad0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
29ae0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
29af0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29b00 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
29b10 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
29b20 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
29b30 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
29b40 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
29b50 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
29b60 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
29b70 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
29b80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
29b90 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
29ba0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
29bb0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
29bc0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
29bd0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
29be0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
29bf0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
29c00 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
29c10 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
29c20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
29c30 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
29c40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
29c50 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
29c60 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
29c70 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
29c80 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
29c90 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
29ca0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
29cb0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
29cc0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
29cd0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
29ce0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
29cf0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
29d00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
29d10 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
29d20 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
29d30 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
29d40 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
29d50 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
29d60 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
29d70 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
29d80 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
29d90 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
29da0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
29db0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
29dc0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
29dd0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
29de0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
29df0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
29e00 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
29e10 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
29e20 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
29e30 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
29e40 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
29e50 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
29e60 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
29e70 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
29e80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
29e90 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
29ea0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
29eb0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
29ec0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
29ed0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
29ee0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
29ef0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
29f00 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
29f10 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
29f20 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
29f30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
29f40 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
29f50 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
29f60 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
29f70 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
29f80 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
29f90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
29fa0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
29fb0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29fc0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
29fd0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
29fe0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
29ff0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
2a000 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2a010 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
2a020 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
2a030 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
2a040 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
2a050 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
2a060 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2a070 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
2a080 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
2a090 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
2a0a0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
2a0b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
2a0c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
2a0d0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
2a0e0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
2a0f0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2a100 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
2a110 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
2a120 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2a130 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
2a140 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
2a150 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
2a160 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
2a170 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
2a180 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
2a190 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2a1a0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
2a1b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2a1c0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
2a1d0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2a1e0 53 65 65 20 74 68 65 20 5b 55 52 49 20 66 69 6c  See the [URI fil
2a1f0 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61  ename] documenta
2a200 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2a210 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2a220 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2a230 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
2a240 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
2a250 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
2a260 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
2a270 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
2a280 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
2a290 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
2a2a0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
2a2b0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
2a2c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a2d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
2a2e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
2a2f0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2a300 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
2a310 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
2a320 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
2a330 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
2a340 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
2a350 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2a360 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
2a370 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
2a380 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
2a390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2a3a0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
2a3b0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
2a3c0 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
2a3d0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
2a3e0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
2a3f0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
2a400 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
2a410 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
2a420 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ll..** ^The sqli
2a430 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2a440 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
2a450 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
2a460 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
2a470 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
2a480 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
2a490 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
2a4a0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
2a4b0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
2a4c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
2a4d0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72  .** The values r
2a4e0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a4f0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64  e3_errcode() and
2a500 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  /or.** sqlite3_e
2a510 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2a520 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77  ) might change w
2a530 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c  ith each API cal
2a540 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68  l..** Except, th
2a550 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74  ere are some int
2a560 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
2a570 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e   guaranteed to n
2a580 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ever.** change t
2a590 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a5a0 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65  error code.  The
2a5b0 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73   error-code pres
2a5c0 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66  erving.** interf
2a5d0 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20  aces are:.**.** 
2a5e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  <ul>.** <li> sql
2a5f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
2a600 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
2a610 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2a620 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2a630 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c  3_errmsg().** <l
2a640 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  i> sqlite3_errms
2a650 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  g16().** </ul>.*
2a660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a670 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2a680 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2a690 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2a6a0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2a6b0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2a6c0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2a6d0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2a6e0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2a6f0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2a700 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2a710 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2a720 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2a730 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2a740 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2a750 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2a760 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2a770 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2a780 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2a790 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2a7a0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2a7b0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2a7c0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2a7d0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2a7e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2a7f0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2a800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2a810 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2a820 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2a830 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2a840 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2a850 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2a860 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2a870 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2a880 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2a890 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2a8a0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2a8b0 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2a8c0 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2a8d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a8e0 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2a8f0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2a900 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2a910 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2a920 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2a930 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2a940 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2a950 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2a960 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2a970 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2a980 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2a990 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2a9a0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2a9b0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2a9c0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2a9d0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2a9e0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2a9f0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2aa00 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2aa10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2aa20 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2aa30 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2aa40 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2aa50 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2aa60 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2aa70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2aa80 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2aa90 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2aaa0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2aab0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2aac0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2aad0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2aae0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2aaf0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2ab00 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2ab10 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2ab20 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2ab30 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2ab40 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2ab50 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2ab60 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2ab70 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2ab80 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2ab90 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2aba0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2abb0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2abc0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2abd0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2abe0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2abf0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2ac00 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
2ac10 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
2ac20 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2ac30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
2ac40 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
2ac50 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
2ac60 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ac70 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
2ac80 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ac90 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
2aca0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2acb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
2acc0 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
2acd0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2ace0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2acf0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2ad00 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
2ad10 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
2ad20 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
2ad30 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
2ad40 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
2ad50 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
2ad60 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
2ad70 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
2ad80 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
2ad90 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
2ada0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
2adb0 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
2adc0 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
2add0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
2ade0 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
2adf0 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
2ae00 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2ae10 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
2ae20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
2ae30 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2ae40 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
2ae50 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
2ae60 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
2ae70 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
2ae80 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
2ae90 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
2aea0 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
2aeb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
2aec0 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
2aed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2aee0 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
2aef0 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
2af00 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2af10 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
2af20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2af30 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2af40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2af50 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
2af60 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
2af70 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
2af80 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2af90 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
2afa0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
2afb0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
2afc0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
2afd0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
2afe0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2aff0 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
2b000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2b010 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2b020 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
2b030 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
2b040 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
2b050 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
2b060 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
2b070 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
2b080 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2b090 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
2b0a0 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
2b0b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
2b0c0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
2b0d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b0e0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
2b0f0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2b100 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
2b110 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
2b120 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
2b130 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
2b140 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
2b150 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
2b160 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
2b170 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
2b180 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2b190 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2b1a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
2b1b0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
2b1c0 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
2b1d0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
2b1e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
2b1f0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
2b200 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
2b210 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
2b220 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
2b230 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
2b240 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
2b250 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b260 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
2b270 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
2b280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
2b290 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
2b2a0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
2b2b0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
2b2c0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
2b2d0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
2b2e0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
2b2f0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
2b300 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
2b310 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
2b320 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
2b330 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
2b340 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
2b350 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
2b360 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
2b370 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
2b380 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
2b390 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
2b3a0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
2b3b0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
2b3c0 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
2b3d0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
2b3e0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
2b3f0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
2b400 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
2b410 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
2b420 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2b430 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
2b440 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2b450 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
2b460 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
2b470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
2b480 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
2b490 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
2b4a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
2b4b0 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
2b4c0 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
2b4d0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
2b4e0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
2b4f0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
2b500 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
2b510 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
2b520 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b530 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
2b540 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
2b550 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
2b560 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
2b570 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
2b580 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
2b590 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
2b5a0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
2b5b0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
2b5c0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
2b5d0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
2b5e0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2b5f0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
2b600 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
2b610 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
2b620 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
2b630 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
2b640 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
2b650 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
2b660 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
2b670 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
2b680 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
2b690 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
2b6a0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
2b6b0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
2b6c0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
2b6d0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
2b6e0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
2b6f0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
2b700 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
2b710 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
2b720 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
2b730 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
2b740 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
2b750 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
2b760 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
2b770 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
2b780 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
2b790 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
2b7a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
2b7b0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
2b7c0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
2b7d0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
2b7e0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
2b7f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2b800 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
2b810 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
2b820 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
2b830 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
2b840 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
2b850 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
2b860 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
2b870 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
2b880 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2b890 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
2b8a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
2b8b0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
2b8c0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
2b8d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b8e0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
2b8f0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
2b900 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
2b910 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
2b920 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
2b930 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2b940 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2b950 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
2b960 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
2b970 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
2b980 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
2b990 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2b9a0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
2b9b0 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
2b9c0 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
2b9d0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
2b9e0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
2b9f0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2ba00 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
2ba10 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
2ba20 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
2ba30 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2ba40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2ba50 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2ba60 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2ba70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ba80 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
2ba90 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
2baa0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
2bab0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
2bac0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2bad0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2bae0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2baf0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2bb00 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2bb10 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2bb20 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
2bb30 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
2bb40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2bb50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2bb60 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
2bb70 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2bb80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2bb90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2bba0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2bbb0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2bbc0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2bbd0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2bbe0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2bbf0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2bc00 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2bc10 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2bc20 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2bc30 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2bc40 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2bc50 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2bc60 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2bc70 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2bc80 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2bc90 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2bca0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2bcb0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2bcc0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2bcd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2bce0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2bcf0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2bd00 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2bd10 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2bd20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2bd30 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2bd40 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2bd50 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2bd60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2bd70 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2bd80 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2bd90 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2bda0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2bdb0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2bdc0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2bdd0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2bde0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2bdf0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2be00 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2be10 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2be20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2be30 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2be40 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2be50 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2be60 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2be70 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2be80 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2be90 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2bea0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2beb0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2bec0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2bed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2bee0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2bef0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2bf00 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2bf10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2bf20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2bf30 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2bf40 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2bf50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bf60 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2bf70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2bf80 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2bf90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2bfa0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2bfb0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2bfc0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2bfd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2bfe0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2bff0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2c000 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c010 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2c020 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2c030 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2c040 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2c050 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2c060 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2c070 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2c080 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2c090 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2c0a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2c0b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2c0c0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2c0d0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2c0e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2c0f0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2c100 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2c110 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2c120 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2c130 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2c140 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2c150 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2c160 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2c170 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c180 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2c190 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2c1a0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2c1b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2c1c0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2c1d0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c1e0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2c1f0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2c200 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2c210 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2c220 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2c230 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2c240 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c250 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2c260 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2c270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c280 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2c290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c2a0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2c2b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2c2c0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2c2d0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2c2e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2c2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c300 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2c310 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2c320 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2c330 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2c340 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2c350 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2c360 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2c370 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2c380 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2c390 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2c3a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2c3b0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2c3c0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2c3d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2c3e0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2c3f0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2c400 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c410 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2c420 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2c430 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c440 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2c450 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2c460 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c470 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2c480 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2c490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c4a0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2c4b0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2c4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c4d0 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a  Prepare Flags.**
2c4e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c4f0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2c500 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61  us flags that ca
2c510 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f  n be passed into
2c520 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20  .** "prepFlags" 
2c530 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2c540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c550 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  e_v3()] and.** [
2c560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c570 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63  6_v3()] interfac
2c580 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c  es..**.** New fl
2c590 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ags may be added
2c5a0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2c5b0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2c5c0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2c5d0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2c5e0 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74  RSISTENT]] ^(<dt
2c5f0 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2c600 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a  PERSISTENT</dt>.
2c610 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2c620 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2c630 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68  TENT flag is a h
2c640 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79  int to the query
2c650 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74   planner.** that
2c660 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2c670 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2c680 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c  retained for a l
2c690 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20  ong time and.** 
2c6a0 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20  probably reused 
2c6b0 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57  many times.)^ ^W
2c6c0 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67  ithout this flag
2c6d0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2c6e0 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20  re_v3()].** and 
2c6f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c700 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20  16_v3()] assume 
2c710 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2c720 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2c730 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73   .** be used jus
2c740 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2c750 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2c760 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2c770 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c780 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2c790 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20  elatively soon. 
2c7a0 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  The current impl
2c7b0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a  ementation acts.
2c7c0 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ** on this hint 
2c7d0 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20  by avoiding the 
2c7e0 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64  use of [lookasid
2c7f0 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20  e memory] so as 
2c800 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74  not to.** deplet
2c810 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74  e the limited st
2c820 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ore of lookaside
2c830 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20   memory. Future 
2c840 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53  versions of.** S
2c850 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e  QLite may act on
2c860 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65   this hint diffe
2c870 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  rently..**.** [[
2c880 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2c890 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53  ORMALIZE]] <dt>S
2c8a0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2c8b0 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  RMALIZE</dt>.** 
2c8c0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2c8d0 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2c8e0 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70   flag is a no-op
2c8f0 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64  . This flag used
2c900 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72  .** to be requir
2c910 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61  ed for any prepa
2c920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68  red statement th
2c930 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65  at wanted to use
2c940 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2c950 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2c960 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48  )] interface.  H
2c970 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b  owever, the.** [
2c980 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2c990 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66  ed_sql()] interf
2c9a0 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c  ace is now avail
2c9b0 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70  able to all.** p
2c9c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c9d0 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ts, regardless o
2c9e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2c9f0 20 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a   they use this.*
2ca00 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  * flag..**.** [[
2ca10 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2ca20 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c  O_VTAB]] <dt>SQL
2ca30 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56  ITE_PREPARE_NO_V
2ca40 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TAB</dt>.** <dd>
2ca50 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2ca60 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20  RE_NO_VTAB flag 
2ca70 63 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63  causes the SQL c
2ca80 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65  ompiler.** to re
2ca90 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65  turn an error (e
2caa0 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45  rror code SQLITE
2cab0 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73  _ERROR) if the s
2cac0 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a  tatement uses.**
2cad0 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62   any virtual tab
2cae0 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  les..** </dl>.*/
2caf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2cb00 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2cb10 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2cb20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
2cb30 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2cb40 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALIZE           
2cb50 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
2cb60 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2cb70 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NO_VTAB         
2cb80 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a          0x04../*
2cb90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2cba0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2cbb0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2cbc0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2cbd0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2cbe0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2cbf0 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2cc00 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2cc10 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2cc20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2cc30 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2cc40 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2cc50 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2cc60 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2cc70 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2cc80 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68  nes.  Or, in oth
2cc90 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20  er words, these 
2cca0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2ccb0 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72  constructors for
2ccc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ccd0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
2cce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66  ..**.** The pref
2ccf0 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f  erred routine to
2cd00 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33   use is [sqlite3
2cd10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20  _prepare_v2()]. 
2cd20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2cd30 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65  _prepare()] inte
2cd40 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20  rface is legacy 
2cd50 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76  and should be av
2cd60 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  oided..** [sqlit
2cd70 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2cd80 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70   has an extra "p
2cd90 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e  repFlags" option
2cda0 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a   that is used.**
2cdb0 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72   for special pur
2cdc0 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  poses..**.** The
2cdd0 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d   use of the UTF-
2cde0 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  8 interfaces is 
2cdf0 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51  preferred, as SQ
2ce00 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a  Lite currently.*
2ce10 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69  * does all parsi
2ce20 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20  ng using UTF-8. 
2ce30 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2ce40 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
2ce50 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76  ded.** as a conv
2ce60 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54  enience.  The UT
2ce70 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2ce80 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69  work by converti
2ce90 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  ng the.** input 
2cea0 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c  text into UTF-8,
2ceb0 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74   then invoking t
2cec0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2ced0 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2cee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2cef0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2cf00 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2cf10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2cf20 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2cf30 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2cf40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2cf50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2cf60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2cf70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2cf80 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2cf90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cfa0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2cfb0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2cfc0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2cfd0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2cfe0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2cff0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2d000 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2d010 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2d020 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2d030 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73  te3_prepare(), s
2d040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d050 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2d060 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2d070 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
2d080 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
2d090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d0a0 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2d0b0 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2d0c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2d0d0 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46  e16_v3() use UTF
2d0e0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2d0f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2d100 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2d110 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2d120 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2d130 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2d140 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2d150 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2d160 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2d170 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2d180 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2d190 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2d1a0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2d1b0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2d1c0 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2d1d0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2d1e0 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2d1f0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2d200 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2d210 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2d220 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2d230 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2d240 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2d250 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2d260 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2d270 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d280 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2d290 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2d2a0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2d2b0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2d2c0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2d2d0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2d2e0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2d2f0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2d300 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2d310 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2d320 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2d330 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2d340 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2d350 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2d360 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2d370 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2d380 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2d390 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2d3a0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2d3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2d3c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2d3d0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2d3e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d3f0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2d400 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2d410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2d420 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2d430 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2d440 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2d450 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2d460 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2d470 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2d480 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2d490 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2d4a0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2d4b0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2d4c0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2d4d0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2d4e0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2d4f0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2d500 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2d510 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2d520 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2d530 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2d540 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2d550 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2d560 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2d570 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2d580 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2d590 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2d5a0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2d5b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2d5c0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2d5d0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2d5e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2d5f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2d600 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c  repare_v2(), sql
2d610 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2d620 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2d630 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2d640 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2d650 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61  e16_v3() interfa
2d660 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e  ces are recommen
2d670 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2d680 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65  programs..** The
2d690 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2d6a0 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s (sqlite3_prepa
2d6b0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
2d6c0 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a  _prepare16()).**
2d6d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
2d6e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2d6f0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2d700 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2d710 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2d720 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
2d730 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2d740 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2d750 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2d760 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2d770 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2d780 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2d790 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2d7a0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2d7b0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2d7c0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2d7d0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2d7e0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2d7f0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2d800 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2d810 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d820 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2d830 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2d840 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2d850 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2d860 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2d870 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2d880 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2d890 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2d8a0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2d8b0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2d8c0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2d8d0 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2d8e0 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2d8f0 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2d900 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2d910 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d920 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2d930 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2d940 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2d950 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2d960 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2d970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2d980 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2d990 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2d9a0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2d9b0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2d9c0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2d9d0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2d9e0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2d9f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2da00 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2da10 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2da20 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2da30 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2da40 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2da50 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2da60 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2da70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2da80 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2da90 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2daa0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2dab0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2dac0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2dad0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2dae0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2daf0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2db00 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2db10 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2db20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2db30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2db40 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2db50 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2db60 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2db70 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2db80 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2db90 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2dba0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2dbb0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2dbc0 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2dbd0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2dbe0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2dbf0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2dc00 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2dc10 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2dc20 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2dc30 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2dc40 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2dc50 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2dc60 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2dc70 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2dc80 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2dc90 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2dca0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2dcb0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2dcc0 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2dcd0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2dce0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2dcf0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2dd00 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2dd10 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2dd20 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2dd30 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2dd40 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2dd50 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2dd60 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2dd70 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2dd80 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2dd90 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2dda0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2ddb0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2ddc0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
2ddd0 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2dde0 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2ddf0 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2de00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2de10 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2de20 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2de30 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2de40 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2de50 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2de60 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2de70 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2de80 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2de90 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2dea0 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2deb0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2dec0 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2ded0 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2dee0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2def0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2df00 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2df10 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2df20 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  rameter..*/.int 
2df30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2df40 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2df50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2df60 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2df70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2df80 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2df90 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2dfa0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2dfb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2dfc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2dfd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2dfe0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2dff0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2e000 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2e010 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2e020 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2e030 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2e040 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2e050 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2e060 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2e070 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2e080 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2e090 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e0a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2e0b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2e0c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2e0d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2e0e0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2e0f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2e100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e110 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2e120 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2e130 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2e140 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2e150 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2e160 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e170 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2e180 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2e190 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2e1a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2e1b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2e1c0 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73  _prepare_v3(.  s
2e1d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e1e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2e1f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2e200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2e210 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2e220 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2e230 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2e240 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2e250 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2e260 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2e270 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2e280 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2e290 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2e2a0 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2e2b0 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2e2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2e2d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2e2e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2e2f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e300 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2e310 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2e320 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2e330 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2e340 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2e350 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2e360 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2e370 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2e380 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2e390 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2e3a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2e3b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2e3c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2e3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e3e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2e3f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2e400 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2e410 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2e420 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2e430 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e440 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2e450 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2e460 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2e470 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2e480 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e490 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
2e4a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e4b0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e4c0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e4d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2e4e0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e4f0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2e500 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2e510 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2e520 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2e530 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2e540 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2e550 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2e560 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2e570 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2e580 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e590 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2e5a0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2e5b0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2e5c0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2e5d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e5e0 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  16_v3(.  sqlite3
2e5f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e600 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2e610 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2e620 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2e630 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2e640 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2e650 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2e660 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2e670 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2e680 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2e690 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2e6a0 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2e6b0 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2e6c0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2e6d0 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2e6e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2e6f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2e700 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2e710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2e720 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2e730 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2e740 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2e750 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2e760 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2e770 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2e780 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2e790 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e7a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2e7b0 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2e7c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e7d0 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2e7e0 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2e7f0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2e800 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2e810 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2e820 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2e830 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e840 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2e850 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
2e860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e870 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
2e880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e890 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54  e16_v3()]..** ^T
2e8a0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2e8b0 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  ded_sql(P) inter
2e8c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e8d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2e8e0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2e8f0 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74  aining the SQL t
2e900 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2e910 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68  statement P with
2e920 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d  .** [bound param
2e930 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e  eters] expanded.
2e940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e950 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2e960 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e970 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e980 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2e990 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2e9a0 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51  he normalized SQ
2e9b0 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2e9c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20  ed statement P. 
2e9d0 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63   The.** semantic
2e9e0 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c  s used to normal
2e9f0 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d  ize a SQL statem
2ea00 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66  ent are unspecif
2ea10 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a  ied and subject.
2ea20 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41  ** to change.  A
2ea30 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74  t a minimum, lit
2ea40 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c  eral values will
2ea50 20 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74   be replaced wit
2ea60 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c  h suitable.** pl
2ea70 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a  aceholders..**.*
2ea80 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2ea90 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2eaa0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2eab0 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2eac0 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2ead0 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2eae0 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2eaf0 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2eb00 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2eb10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2eb20 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2eb30 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2eb40 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2eb50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2eb60 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2eb70 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2eb80 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2eb90 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2eba0 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2ebb0 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2ebc0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2ebd0 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2ebe0 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2ebf0 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2ec00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2ec10 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2ec20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2ec30 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2ec40 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2ec50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2ec60 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2ec70 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2ec80 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2ec90 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2eca0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2ecb0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2ecc0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2ecd0 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2ece0 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2ecf0 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2ed00 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2ed10 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2ed20 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2ed30 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2ed40 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2ed50 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2ed60 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2ed70 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
2ed80 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2ed90 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e  P) and sqlite3_n
2eda0 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29  ormalized_sql(P)
2edb0 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20  .** are managed 
2edc0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72  by SQLite and ar
2edd0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2ede0 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2edf0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2ee00 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2ee10 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2ee20 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2ee30 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2ee40 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2ee50 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2ee60 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2ee70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2ee80 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2ee90 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2eea0 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2eeb0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2eec0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2eed0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2eee0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2eef0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2ef00 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2ef10 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2ef20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e  tmt *pStmt);.con
2ef30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ef40 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2ef50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ef60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ef70 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2ef80 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2ef90 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2efa0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2efb0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2efc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2efd0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2efe0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2eff0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2f000 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2f010 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2f020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f030 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2f040 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2f050 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2f060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2f070 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2f080 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2f090 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2f0a0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2f0b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2f0c0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2f0d0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2f0e0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2f0f0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2f100 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2f110 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2f120 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2f130 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2f140 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2f150 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2f160 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2f170 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2f180 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2f190 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2f1a0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2f1b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2f1c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2f1d0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2f1e0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2f1f0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2f200 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2f210 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2f220 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2f230 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2f240 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2f250 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2f260 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2f270 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2f280 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2f290 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2f2a0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2f2b0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2f2c0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2f2d0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2f2e0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2f2f0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2f300 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2f310 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2f320 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2f330 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2f340 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2f350 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2f360 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2f370 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2f380 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2f390 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2f3a0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2f3b0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2f3c0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2f3d0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2f3e0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2f3f0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2f400 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2f410 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2f420 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2f430 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2f440 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2f450 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2f460 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2f470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2f480 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2f490 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2f4a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2f4b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2f4c0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2f4d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2f4e0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2f4f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2f500 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2f510 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2f520 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2f530 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2f540 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2f550 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2f560 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2f570 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2f580 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2f590 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2f5a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2f5b0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2f5c0 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2f5d0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2f5e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2f5f0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2f600 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f620 3a 20 51 75 65 72 79 20 54 68 65 20 45 58 50 4c  : Query The EXPL
2f630 41 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20  AIN Setting For 
2f640 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2f650 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2f660 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f680 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53  stmt_isexplain(S
2f690 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f6a0 72 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20  rns 1 if the.** 
2f6b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f6c0 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41  nt S is an EXPLA
2f6d0 49 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  IN statement, or
2f6e0 20 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61   2 if the.** sta
2f6f0 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45  tement S is an E
2f700 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
2f710 4e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  N..** ^The sqlit
2f720 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69  e3_stmt_isexplai
2f730 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  n(S) interface r
2f740 65 74 75 72 6e 73 20 30 20 69 66 20 53 20 69 73  eturns 0 if S is
2f750 0a 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20  .** an ordinary 
2f760 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e  statement or a N
2f770 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
2f780 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2f790 5f 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69 74  _isexplain(sqlit
2f7a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f7b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f7c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2f7d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f7e0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2f7f0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f800 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2f820 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2f830 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2f840 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2f850 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f860 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2f870 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2f880 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2f890 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2f8a0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2f8b0 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2f8c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2f8d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2f8e0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2f8f0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2f900 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2f910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2f920 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2f930 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2f940 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2f950 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2f960 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2f970 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2f980 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2f990 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2f9a0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2f9b0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2f9c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f9d0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2f9e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2f9f0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2fa00 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2fa10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2fa20 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2fa30 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2fa40 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2fa50 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2fa60 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2fa70 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2fa80 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2fa90 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2faa0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2fab0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2fac0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2fad0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2fae0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2faf0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2fb00 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2fb10 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2fb20 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2fb30 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2fb40 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2fb50 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2fb60 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2fb70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2fb80 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2fb90 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2fba0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2fbb0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2fbc0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2fbd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fbe0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2fbf0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2fc00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fc10 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2fc20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2fc30 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2fc40 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2fc50 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2fc60 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2fc70 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2fc80 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2fc90 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2fca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2fcb0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2fcc0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2fcd0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2fce0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2fcf0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2fd00 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2fd10 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2fd20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2fd30 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2fd40 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2fd50 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2fd60 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2fd70 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2fd80 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2fd90 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2fda0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2fdb0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2fdc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2fdd0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2fde0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2fdf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2fe00 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2fe10 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2fe20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2fe30 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2fe40 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2fe50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2fe60 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2fe70 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2fe80 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2fe90 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2fea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2feb0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2fec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2fed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2fee0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2fef0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2ff00 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2ff10 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2ff20 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2ff30 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2ff40 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2ff50 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2ff60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2ff70 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2ff80 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2ff90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2ffa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2ffb0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2ffc0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2ffd0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2ffe0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2fff0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
30000 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
30010 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
30020 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
30030 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
30040 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
30050 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
30060 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30070 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
30080 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30090 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
300a0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
300b0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
300c0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
300d0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
300e0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
300f0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
30100 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
30110 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
30120 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
30130 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
30140 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
30150 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
30160 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
30170 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
30180 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
30190 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
301a0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
301b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
301c0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
301d0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
301e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
301f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30200 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
30210 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
30220 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
30230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30240 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
30250 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30260 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
30270 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
30280 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30290 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
302a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
302b0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
302c0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
302d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
302e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
302f0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
30300 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
30310 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
30320 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
30330 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30340 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
30350 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
30360 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
30370 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
30380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30390 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
303a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
303b0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
303c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
303d0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
303e0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
303f0 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
30400 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
30410 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
30420 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
30430 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
30440 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
30450 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
30460 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
30470 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
30480 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
30490 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
304a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
304b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
304c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
304d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
304e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
304f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
30500 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
30510 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30520 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
30530 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
30540 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
30550 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
30560 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30570 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
30580 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
30590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
305a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
305b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
305c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
305d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
305e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
305f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30600 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
30610 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30620 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
30630 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30640 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
30650 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
30660 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
30670 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
30680 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30690 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
306a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
306b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
306c0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
306d0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
306e0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
306f0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
30700 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
30710 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
30720 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30730 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
30740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
30750 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
30760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30770 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
30780 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
30790 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
307a0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
307b0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
307c0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
307d0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
307e0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
307f0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
30800 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
30810 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
30820 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
30830 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
30840 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
30850 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
30860 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
30870 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
30880 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
30890 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
308a0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
308b0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
308c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
308d0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
308e0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
308f0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
30900 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
30910 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
30920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
30930 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
30940 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
30950 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30960 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
30970 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
30980 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
30990 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
309a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
309b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
309c0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
309d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
309e0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
309f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30a00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
30a10 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
30a20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
30a30 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
30a40 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
30a50 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
30a60 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
30a70 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
30a80 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
30a90 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
30aa0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
30ab0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
30ac0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
30ad0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
30ae0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
30af0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
30b00 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
30b10 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
30b20 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
30b30 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
30b40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30b50 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
30b60 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
30b70 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
30b80 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
30b90 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
30ba0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
30bb0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
30bc0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
30bd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
30be0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
30bf0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
30c00 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
30c10 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
30c20 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
30c30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
30c40 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
30c50 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
30c60 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
30c70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30c80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
30c90 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
30ca0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
30cb0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30cc0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
30cd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
30ce0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
30cf0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
30d00 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
30d10 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
30d20 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
30d30 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
30d40 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
30d50 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
30d60 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
30d70 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
30d80 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
30d90 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
30da0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
30db0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
30dc0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
30dd0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
30de0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
30df0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
30e00 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
30e10 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
30e20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
30e30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30e40 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
30e50 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
30e60 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
30e70 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
30e80 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
30e90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
30ea0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
30eb0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
30ec0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
30ed0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
30ee0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
30ef0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
30f00 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
30f10 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
30f20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
30f30 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
30f40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
30f50 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
30f60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30f70 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
30f80 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
30f90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30fa0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
30fb0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
30fc0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
30fd0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
30fe0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
30ff0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
31000 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
31010 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
31020 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
31030 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
31040 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
31050 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
31060 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
31070 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
31080 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
31090 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
310a0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
310b0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
310c0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
310d0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
310e0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
310f0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
31100 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
31110 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31120 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
31130 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
31140 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
31150 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31160 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
31170 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
31180 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
31190 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
311a0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
311b0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
311c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
311d0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
311e0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
311f0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
31200 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
31210 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
31220 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
31230 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
31240 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
31250 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
31260 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
31270 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
31280 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
31290 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
312a0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
312b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
312c0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
312d0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
312e0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
312f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
31300 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
31310 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
31320 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
31330 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
31340 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
31350 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
31360 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
31370 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
31380 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
31390 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
313a0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
313b0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
313c0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
313d0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
313e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
313f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
31400 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
31410 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
31420 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
31430 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
31440 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
31450 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
31460 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
31470 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
31480 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
31490 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
314a0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
314b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
314c0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
314d0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
314e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
314f0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
31500 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
31510 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
31520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
31530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
31540 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
31550 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
31560 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
31570 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
31580 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
31590 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
315a0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
315b0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
315c0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
315d0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
315e0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
315f0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
31600 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
31610 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
31620 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
31630 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
31640 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
31650 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
31660 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
31670 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
31680 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
31690 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
316a0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
316b0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
316c0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
316d0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
316e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
316f0 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
31700 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
31710 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
31720 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
31730 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31740 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
31750 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
31760 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
31770 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31780 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
31790 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
317a0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
317b0 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
317c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
317d0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
317e0 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
317f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
31800 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
31810 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
31820 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
31830 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
31840 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
31850 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
31860 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
31870 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
31880 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
31890 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
318a0 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
318b0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
318c0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
318d0 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
318e0 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
318f0 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
31900 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
31910 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
31920 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
31930 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
31940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
31950 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
31960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
31970 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
31980 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
31990 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
319a0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
319b0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
319c0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
319d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
319e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
319f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
31a00 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
31a10 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
31a20 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
31a30 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
31a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31a50 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
31a60 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
31a70 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
31a80 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
31a90 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
31aa0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
31ab0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
31ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31ad0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
31ae0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
31af0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
31b00 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
31b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31b20 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
31b30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
31b40 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
31b50 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
31b60 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
31b70 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
31b80 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
31b90 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
31ba0 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
31bb0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
31bc0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
31bd0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
31be0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31bf0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
31c00 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
31c10 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
31c20 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
31c30 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
31c40 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
31c50 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
31c60 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
31c70 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
31c80 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
31c90 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
31ca0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31cb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31cc0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
31cd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
31ce0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
31cf0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
31d00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
31d10 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
31d20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31d30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31d40 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
31d50 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
31d60 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
31d70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
31d80 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
31d90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
31da0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
31db0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
31dc0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
31dd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
31de0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
31df0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
31e00 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
31e10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
31e20 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
31e30 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
31e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
31e50 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
31e60 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
31e70 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
31e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
31e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31ea0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
31eb0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
31ec0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
31ed0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
31ee0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
31ef0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
31f00 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
31f10 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
31f20 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
31f30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
31f40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
31f50 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
31f60 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
31f70 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
31f80 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
31f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31fa0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
31fb0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
31fc0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
31fd0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
31fe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31ff0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
32000 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
32010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
32020 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
32030 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
32040 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
32050 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
32060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
32070 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
32080 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
32090 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
320a0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
320b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
320c0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
320d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
320e0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
320f0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
32100 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32110 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
32120 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
32130 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
32140 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
32150 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
32160 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
32170 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
32180 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
32190 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
321a0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
321b0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
321c0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
321d0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
321e0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
321f0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
32200 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
32210 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
32220 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
32230 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
32240 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
32250 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
32260 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
32270 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
32280 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
32290 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
322a0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
322b0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
322c0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
322d0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
322e0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
322f0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
32300 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
32310 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
32320 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
32330 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
32340 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
32350 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
32360 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
32370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
32380 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
32390 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
323a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
323b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
323c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
323d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
323e0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
323f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32400 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
32410 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
32420 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32430 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
32440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
32450 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
32460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32470 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
32480 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
32490 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
324a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
324b0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
324c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
324d0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
324e0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
324f0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
32500 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
32510 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
32520 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
32530 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
32540 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
32550 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
32560 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
32570 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
32580 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
32590 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
325a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
325b0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
325c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
325d0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
325e0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
325f0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
32600 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
32610 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
32620 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
32630 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
32640 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
32650 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
32660 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
32670 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
32680 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
32690 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
326a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
326b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
326c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
326d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
326e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
326f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
32700 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
32710 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
32720 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
32730 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
32740 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
32750 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
32760 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
32770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32780 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
32790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
327a0 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
327b0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
327c0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
327d0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
327e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
327f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
32800 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
32810 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32820 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
32830 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32840 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32850 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
32860 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
32870 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
32880 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
32890 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
328a0 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
328b0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
328c0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
328d0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
328e0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
328f0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
32900 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
32910 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
32920 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
32930 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
32940 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
32950 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
32960 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
32970 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
32980 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
32990 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
329a0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
329b0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
329c0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
329d0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
329e0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
329f0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
32a00 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
32a10 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
32a20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32a30 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
32a40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32a50 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
32a60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
32a70 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
32a80 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
32a90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32aa0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
32ab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
32ac0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
32ad0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
32ae0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32af0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
32b00 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
32b10 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
32b20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
32b30 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
32b40 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
32b50 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
32b60 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32b70 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
32b80 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
32b90 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
32ba0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
32bb0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
32bc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
32bd0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
32be0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
32bf0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
32c00 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
32c10 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
32c20 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
32c30 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
32c40 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
32c50 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
32c60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32c70 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
32c80 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
32c90 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
32ca0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32cb0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
32cc0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
32cd0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
32ce0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
32cf0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
32d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
32d10 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
32d20 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
32d30 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
32d40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32d50 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
32d60 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
32d70 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
32d80 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
32d90 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
32da0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
32db0 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
32dc0 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
32dd0 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
32de0 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
32df0 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
32e00 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
32e10 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
32e20 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
32e30 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
32e40 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
32e50 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
32e60 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
32e70 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
32e80 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
32e90 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
32ea0 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
32eb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32ec0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
32ed0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
32ee0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
32ef0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32f00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32f10 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
32f20 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
32f30 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
32f40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32f50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32f60 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
32f70 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
32f80 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
32f90 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
32fa0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
32fb0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
32fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
32fd0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
32fe0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32ff0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
33000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
33010 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
33020 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33030 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
33040 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
33050 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
33060 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
33070 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
33080 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
33090 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
330a0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
330b0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
330c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
330d0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
330e0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
330f0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
33100 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
33110 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
33120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
33130 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
33140 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
33150 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
33160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33170 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
33180 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
33190 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
331a0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
331b0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
331c0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
331d0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
331e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
331f0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
33200 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
33210 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
33220 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
33230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
33240 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
33250 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
33260 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
33270 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
33280 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
33290 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
332a0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
332b0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
332c0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
332d0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
332e0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
332f0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
33300 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
33310 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
33320 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
33330 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
33340 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
33350 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
33360 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
33370 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
33380 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
33390 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
333a0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
333b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
333c0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
333d0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
333e0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
333f0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
33400 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
33410 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
33420 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
33430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33440 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
33450 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33460 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
33470 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
33480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33490 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
334a0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
334b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
334c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
334d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
334e0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
334f0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
33500 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
33510 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
33520 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
33530 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
33540 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
33550 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
33560 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
33570 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33580 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
33590 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
335a0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
335b0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
335c0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
335d0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
335e0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
335f0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
33600 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
33610 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
33620 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
33630 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
33640 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
33650 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
33660 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
33670 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
33680 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
33690 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
336a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
336b0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
336c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
336d0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
336e0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
336f0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
33700 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
33710 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
33720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33730 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
33740 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
33750 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
33760 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
33770 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
33780 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
33790 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
337a0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
337b0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
337c0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
337d0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
337e0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
337f0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
33800 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
33810 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
33820 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
33830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33840 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
33850 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
33860 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
33870 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
33880 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
33890 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
338a0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
338b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
338c0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
338d0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
338e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
338f0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
33900 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
33910 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
33920 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
33930 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
33940 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
33950 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
33960 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
33970 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
33980 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
33990 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
339a0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
339b0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
339c0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
339d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
339e0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
339f0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
33a00 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
33a10 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
33a20 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
33a30 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
33a40 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
33a50 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
33a60 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
33a70 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
33a80 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
33a90 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
33aa0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
33ab0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
33ac0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
33ad0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
33ae0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
33af0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
33b00 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
33b10 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
33b20 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
33b30 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
33b40 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
33b50 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
33b60 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
33b70 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
33b80 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
33b90 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
33ba0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
33bb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33bc0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
33bd0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
33be0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
33bf0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
33c00 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
33c10 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
33c20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
33c30 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
33c40 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
33c50 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
33c60 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
33c70 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
33c80 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
33c90 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
33ca0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
33cb0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
33cc0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
33cd0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
33ce0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
33cf0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
33d00 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
33d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
33d20 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
33d30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
33d40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33d50 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
33d60 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
33d70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
33d80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
33d90 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
33da0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
33db0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
33dc0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
33dd0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
33de0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
33df0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
33e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
33e10 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
33e20 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
33e30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33e40 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
33e50 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
33e60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
33e70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
33e80 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
33e90 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
33ea0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33eb0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
33ec0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
33ed0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
33ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33ef0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
33f00 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
33f10 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
33f20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
33f30 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
33f40 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
33f50 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
33f60 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
33f70 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
33f80 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
33f90 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
33fa0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
33fb0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
33fc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
33fd0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
33fe0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
33ff0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
34000 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
34010 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
34020 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
34030 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
34040 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
34050 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
34060 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
34070 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
34080 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
34090 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
340a0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
340b0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
340c0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
340d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
340e0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
340f0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
34100 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
34110 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
34120 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
34130 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
34140 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
34150 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
34160 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
34170 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
34180 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
34190 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
341a0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
341b0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
341c0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
341d0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
341e0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
341f0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
34200 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
34210 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
34220 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
34230 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
34240 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
34250 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
34260 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
34270 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
34280 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
34290 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
342a0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
342b0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
342c0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
342d0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
342e0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
342f0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
34300 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
34310 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
34320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
34330 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
34340 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
34350 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
34360 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
34370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
34380 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
34390 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
343a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
343b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
343c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
343d0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
343e0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
343f0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
34400 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
34410 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
34420 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
34430 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
34440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
34450 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
34460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
34470 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
34480 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
34490 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
344a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
344b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
344c0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
344d0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
344e0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
344f0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
34500 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
34510 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
34520 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
34530 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
34540 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
34550 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
34560 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
34570 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
34580 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
34590 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
345a0 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
345b0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
345c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
345d0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
345e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
345f0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
34600 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
34610 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
34620 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
34630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34640 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34650 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
34660 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
34670 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
34680 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
34690 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
346a0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
346b0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
346c0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
346d0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
346e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
346f0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
34700 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
34710 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
34720 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
34730 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
34740 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
34750 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
34760 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
34770 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
34780 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
34790 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
347a0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
347b0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
347c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
347d0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
347e0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
347f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
34800 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
34810 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
34820 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
34830 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
34840 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
34850 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
34860 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
34870 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
34880 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
34890 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
348a0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
348b0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
348c0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
348d0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
348e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
348f0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
34900 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
34910 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
34920 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
34930 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
34940 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
34950 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
34960 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
34970 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
34980 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
34990 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
349a0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
349b0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
349c0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
349d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
349e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
349f0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
34a00 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
34a10 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
34a20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34a30 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
34a40 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
34a50 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
34a60 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
34a70 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
34a80 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
34a90 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
34aa0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
34ab0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
34ac0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
34ad0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
34ae0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
34af0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
34b00 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
34b10 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
34b20 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
34b30 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
34b40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
34b50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
34b60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
34b70 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
34b80 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
34b90 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
34ba0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
34bb0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
34bc0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
34bd0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
34be0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
34bf0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
34c00 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
34c10 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
34c20 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
34c30 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
34c40 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
34c50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
34c60 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
34c70 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
34c80 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
34c90 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
34ca0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
34cb0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
34cc0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
34cd0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
34ce0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
34cf0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
34d00 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
34d10 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
34d20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
34d30 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34d40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
34d50 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
34d60 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
34d70 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
34d80 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
34d90 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
34da0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
34db0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
34dc0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
34dd0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
34de0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
34df0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
34e00 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
34e10 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
34e20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34e30 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
34e40 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
34e50 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
34e60 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
34e70 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
34e80 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
34e90 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
34ea0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
34eb0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
34ec0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
34ed0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
34ee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34ef0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
34f00 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
34f10 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
34f20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
34f30 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
34f40 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
34f50 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
34f60 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
34f70 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
34f80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34f90 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
34fa0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
34fb0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
34fc0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
34fd0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
34fe0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
34ff0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
35000 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
35010 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
35020 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
35030 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35040 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
35050 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
35060 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
35070 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
35080 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
35090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
350a0 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
350b0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
350c0 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
350d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
350e0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
350f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
35100 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
35110 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
35120 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
35130 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
35140 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
35150 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
35160 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
35170 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
35180 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
35190 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
351a0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
351b0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
351c0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
351d0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
351e0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
351f0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
35200 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
35210 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
35220 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
35230 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
35240 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
35250 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
35260 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
35270 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
35280 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
35290 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
352a0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
352b0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
352c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
352d0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
352e0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
352f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
35300 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
35310 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
35320 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
35330 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
35340 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
35350 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
35360 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
35370 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
35380 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
35390 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
353a0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
353b0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
353c0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
353d0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
353e0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
353f0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
35400 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
35410 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
35420 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
35430 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
35440 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
35450 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
35460 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
35470 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
35480 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
35490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
354a0 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
354b0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
354c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
354d0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
354e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
354f0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
35500 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
35510 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
35520 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
35530 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
35540 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
35550 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
35560 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
35570 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
35580 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
35590 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
355a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
355b0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
355c0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
355d0 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
355e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
355f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35600 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
35610 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35620 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
35630 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
35640 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
35650 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
35660 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
35670 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
35680 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35690 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
356a0 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
356b0 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
356c0 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
356d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
356e0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
356f0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
35700 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
35710 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
35720 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
35730 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
35740 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
35750 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
35760 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
35770 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35790 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
357a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
357b0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
357c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
357d0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
357e0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
357f0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
35800 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
35810 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
35820 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
35830 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
35840 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
35850 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
35860 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
35870 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
35880 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
35890 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
358a0 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
358b0 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
358c0 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
358d0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
358e0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
358f0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
35900 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
35910 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
35920 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
35930 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
35940 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
35950 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
35960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35970 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
35980 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
35990 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
359a0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
359b0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
359c0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
359d0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
359e0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
359f0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
35a00 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35a10 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
35a20 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
35a30 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
35a40 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
35a50 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
35a60 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
35a70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
35a80 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
35a90 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
35aa0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
35ab0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
35ac0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
35ad0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
35ae0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
35af0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
35b00 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
35b10 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
35b20 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
35b30 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
35b40 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
35b50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
35b60 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
35b70 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
35b80 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
35b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35ba0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
35bb0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
35bc0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
35bd0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
35be0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
35bf0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
35c00 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
35c10 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
35c20 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
35c30 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
35c40 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
35c50 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
35c60 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
35c70 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
35c80 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
35c90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
35ca0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
35cb0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
35cc0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
35cd0 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
35ce0 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
35cf0 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
35d00 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
35d10 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
35d20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35d40 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
35d50 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
35d60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
35d80 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
35d90 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
35da0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35db0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35dc0 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
35dd0 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
35de0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
35df0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
35e00 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
35e10 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
35e20 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
35e30 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
35e40 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
35e50 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
35e60 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
35e70 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
35e80 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35e90 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
35ea0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
35eb0 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
35ec0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35ed0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
35ee0 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
35ef0 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
35f00 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
35f10 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
35f20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35f30 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
35f40 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
35f50 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
35f60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35f80 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
35f90 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
35fa0 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
35fb0 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
35fc0 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
35fd0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
35fe0 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
35ff0 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
36000 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
36010 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
36020 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
36030 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
36040 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
36050 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
36060 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
36070 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
36080 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
36090 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
360a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
360b0 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
360c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
360d0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
360e0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
360f0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
36100 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
36110 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
36120 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
36130 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
36140 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
36150 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
36160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36170 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
36180 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
36190 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
361a0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
361b0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
361c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
361d0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
361e0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
361f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
36200 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
36210 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
36220 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
36230 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
36240 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
36250 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
36260 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
36270 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
36280 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
36290 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
362a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
362b0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
362c0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
362d0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
362e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
362f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
36300 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
36310 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
36320 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
36330 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
36340 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
36350 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
36360 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
36370 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
36380 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
36390 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
363a0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
363b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
363c0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
363d0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
363e0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
363f0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
36400 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36410 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
36420 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
36430 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
36440 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
36450 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
36460 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
36470 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
36480 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
36490 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
364a0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
364b0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
364c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
364d0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
364e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
364f0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
36500 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
36510 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
36520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
36530 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
36540 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
36550 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
36560 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
36570 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
36580 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
36590 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
365a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
365b0 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
365c0 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
365d0 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
365e0 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
365f0 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
36600 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
36610 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
36620 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
36630 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
36640 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
36650 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
36660 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
36670 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
36680 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
36690 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
366a0 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
366b0 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
366c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
366d0 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
366e0 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
366f0 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
36700 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
36710 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
36720 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
36730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
36750 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
36760 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
36770 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
36780 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
36790 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
367a0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
367b0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
367c0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
367d0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
367e0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
367f0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
36800 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
36810 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
36820 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
36830 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
36840 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
36850 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
36860 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
36870 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
36880 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
36890 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
368a0 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
368b0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
368c0 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
368d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
368e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
368f0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
36900 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
36910 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
36920 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
36930 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
36940 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
36950 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
36960 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
36970 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
36980 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
36990 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
369a0 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
369b0 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
369c0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
369d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
369e0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
369f0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
36a00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
36a10 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
36a20 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
36a30 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
36a40 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
36a50 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
36a60 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
36a70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
36a80 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
36a90 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
36aa0 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
36ab0 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
36ac0 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
36ad0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
36ae0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
36af0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
36b00 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
36b10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
36b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36b30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
36b40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
36b50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
36b60 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
36b70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
36b80 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
36b90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
36ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36bb0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
36bc0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
36bd0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
36be0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
36bf0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
36c00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
36c10 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
36c20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
36c30 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
36c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
36c50 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
36c60 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
36c70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
36c80 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
36c90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
36ca0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
36cb0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
36cc0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
36cd0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
36ce0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
36cf0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
36d00 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
36d10 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
36d20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
36d30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36d40 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
36d50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
36d60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36d70 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
36d80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
36d90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
36da0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
36db0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
36dc0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
36dd0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
36de0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
36df0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
36e00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36e10 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
36e20 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
36e30 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
36e40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36e50 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
36e60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
36e70 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
36e80 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
36e90 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
36ea0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
36eb0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
36ec0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
36ed0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
36ee0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
36ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36f00 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
36f10 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
36f20 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
36f30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
36f40 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
36f50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
36f60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
36f70 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
36f80 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
36f90 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
36fa0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
36fb0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
36fc0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
36fd0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
36fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36ff0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
37010 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
37020 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
37030 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
37040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
37050 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
37060 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
37070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
37080 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
37090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
370a0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
370b0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
370c0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
370d0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
370e0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
370f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
37100 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
37110 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
37120 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
37130 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
37140 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
37150 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
37160 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
37170 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
37180 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
37190 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
371a0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
371b0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
371c0 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
371d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
371e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
371f0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
37200 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
37210 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
37220 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
37230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37240 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
37250 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37260 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37270 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
37280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
37290 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
372a0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
372b0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
372c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
372d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
372e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
372f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37300 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
37310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
37320 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
37330 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
37340 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
37350 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
37360 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
37370 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
37380 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
37390 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
373a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
373b0 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
373c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
373d0 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
373e0 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
373f0 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
37400 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
37410 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
37420 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
37430 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
37440 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
37450 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
37460 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
37470 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
37480 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
37490 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
374a0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
374b0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
374c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
374d0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
374e0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
374f0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
37500 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
37510 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
37520 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
37530 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
37540 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
37550 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
37560 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
37570 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
37580 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
37590 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
375a0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
375b0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
375c0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
375d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
375e0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
375f0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
37600 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
37610 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
37620 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
37630 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
37640 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
37650 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
37660 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
37670 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
37680 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
37690 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
376a0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
376b0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
376c0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
376d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
376e0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
376f0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
37700 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
37710 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
37720 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
37730 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
37740 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
37750 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
37760 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
37770 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
37780 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
37790 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
377a0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
377b0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
377c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
377d0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
377e0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
377f0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
37800 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
37810 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
37820 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
37830 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
37840 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
37850 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
37860 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
37870 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
37880 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
37890 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
378a0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
378b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
378c0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
378d0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
378e0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
378f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
37900 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
37910 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
37920 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
37930 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
37940 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
37950 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
37960 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
37970 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
37980 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
37990 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
379a0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
379b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
379c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
379d0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
379e0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
379f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
37a00 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
37a10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
37a20 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
37a30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
37a40 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
37a50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37a60 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
37a70 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
37a80 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
37a90 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
37aa0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
37ab0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
37ac0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
37ad0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
37ae0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
37af0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
37b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37b10 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
37b20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
37b30 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
37b40 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
37b50 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
37b60 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
37b70 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
37b80 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
37b90 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
37ba0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
37bb0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
37bc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37bd0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
37be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37bf0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
37c00 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
37c10 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
37c20 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
37c30 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
37c40 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
37c50 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
37c60 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
37c70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
37c80 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
37c90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
37ca0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
37cb0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
37cc0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
37cd0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
37ce0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
37cf0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
37d00 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
37d10 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
37d20 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
37d30 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
37d40 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
37d50 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
37d60 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
37d70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
37d80 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
37d90 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
37da0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
37db0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
37dc0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
37dd0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
37de0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
37df0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
37e00 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
37e10 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
37e20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
37e30 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
37e40 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
37e50 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
37e60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
37e70 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
37e80 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
37e90 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
37ea0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
37eb0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
37ec0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
37ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37ee0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
37ef0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37f00 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
37f10 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
37f20 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
37f30 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
37f40 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
37f50 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
37f60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
37f70 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
37f80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37f90 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
37fa0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
37fb0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
37fc0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
37fd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
37fe0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
37ff0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
38000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
38010 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
38020 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
38030 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
38040 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
38050 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
38060 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
38070 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
38080 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
38090 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
380a0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
380b0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
380c0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
380d0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
380e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
380f0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
38100 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
38110 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
38120 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
38130 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
38140 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
38150 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
38160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
38170 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
38180 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
38190 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
381a0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
381b0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
381c0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
381d0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
381e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
381f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
38200 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
38210 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
38220 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
38230 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
38240 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
38250 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
38260 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
38270 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
38280 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
38290 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
382a0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
382b0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
382c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
382d0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
382e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
382f0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  ]..**.** As long
38300 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 70 61   as the input pa
38310 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 6f 72  rameters are cor
38320 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f 75 74  rect, these rout
38330 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a  ines will only.*
38340 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f 75 74  * fail if an out
38350 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72  -of-memory error
38360 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
38370 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73 69   format conversi
38380 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20  on..** Only the 
38390 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65 74  following subset
383a0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 61   of interfaces a
383b0 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 6f 75  re subject to ou
383c0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65  t-of-memory.** e
383d0 72 72 6f 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rrors:.**.** <ul
383e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
383f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a  3_column_blob().
38400 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
38410 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a  column_text().**
38420 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
38430 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
38440 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
38450 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
38460 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
38470 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
38480 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ul>.**.** If 
38490 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  an out-of-memory
384a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 74   error occurs, t
384b0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
384c0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 73 65 0a  alue from these.
384d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 69 73 20 74  ** routines is t
384e0 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 68  he same as if th
384f0 65 20 63 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e  e column had con
38500 74 61 69 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55  tained an SQL NU
38510 4c 4c 20 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c  LL value..** Val
38520 69 64 20 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75  id SQL NULL retu
38530 72 6e 73 20 63 61 6e 20 62 65 20 64 69 73 74 69  rns can be disti
38540 6e 67 75 69 73 68 65 64 20 66 72 6f 6d 20 6f 75  nguished from ou
38550 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
38560 72 73 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e  rs.** by invokin
38570 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  g the [sqlite3_e
38580 72 72 63 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69  rrcode()] immedi
38590 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65 20  ately after the 
385a0 73 75 73 70 65 63 74 0a 2a 2a 20 72 65 74 75 72  suspect.** retur
385b0 6e 20 76 61 6c 75 65 20 69 73 20 6f 62 74 61 69  n value is obtai
385c0 6e 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ned and before a
385d0 6e 79 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ny.** other SQLi
385e0 74 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  te interface is 
385f0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 73 61  called on the sa
38600 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
38610 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e  nection]..*/.con
38620 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
38630 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
38640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
38650 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
38660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
38670 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
38680 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
38690 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
386a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
386b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
386c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
386d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
386e0 34 2