/ Hex Artifact Content
Login

Artifact 3caebc8ebe931db8ba2466395c8f1219ec0fba8828f87c65fa40989d2f2249a6:


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 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68e0: 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45  E_OPEN_FILEPROTE
68f0: 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20  CTION_MASK      
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6910: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37             0x007
6920: 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76  00000../* Reserv
6930: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6950: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6960: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6970: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6980: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6990: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
69a0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
69b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
69c0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
69d0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
69e0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
69f0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6a00: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6a10: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6a20: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6a30: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6a40: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6a50: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6a60: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6a70: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6a80: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** 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 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6ab0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6ac0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6ad0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6ae0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6af0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6b00: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6b10: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6b20: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6b30: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6b40: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6b50: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6b60: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6b70: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6b80: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6b90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6ba0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6bb0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6bc0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6bd0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6be0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6bf0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6c00: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6c10: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6c20: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6c30: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6c40: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6c50: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6c60: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6c70: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6c80: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6c90: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6ca0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6cb0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6cc0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6cd0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6ce0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6cf0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6d00: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6d10: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6d20: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6d30: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6d40: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6d50: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6d60: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6d70: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6d80: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6d90: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6da0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6db0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6dc0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6dd0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6de0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6df0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6e00: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6e10: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6e20: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
6e30: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6e40: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6e50: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6e60: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6e70: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6e80: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6e90: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6ea0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6eb0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6ec0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6ed0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6ee0: 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  vileges..**.** T
6ef0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6f00: 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f  BATCH_ATOMIC pro
6f10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6f20: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
6f30: 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75  ** filesystem su
6f40: 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c  pports doing mul
6f50: 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72  tiple write oper
6f60: 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c  ations atomicall
6f70: 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20  y when those.** 
6f80: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
6f90: 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 62   are bracketed b
6fa0: 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  y [SQLITE_FCNTL_
6fb0: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
6fc0: 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  TE] and.** [SQLI
6fd0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
6fe0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
6ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7000: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
7010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7020: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
7030: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7040: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
7050: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
7060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7070: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
7080: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7090: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
70a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70b0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
70c0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
70d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
70e0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
70f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7100: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
7110: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7120: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
7130: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
7140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7150: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
7160: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7170: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
7180: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7190: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
71a0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
71b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
71c0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
71d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
71e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7200: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
7210: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
7220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7230: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
7240: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
7250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7260: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
7270: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
7280: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
7290: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
72a0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
72b0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
72c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
72d0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
72e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
72f0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
7300: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
7310: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
7320: 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a  0x00004000../*.*
7330: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
7340: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
7350: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
7360: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
7370: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
7380: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
7390: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
73a0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
73b0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
73c0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
73d0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
73e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
73f0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
7400: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7410: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
7420: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7430: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
7440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7450: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
7460: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
7470: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
7480: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
7490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
74a0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
74b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
74c0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
74d0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
74e0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
74f0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
7500: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
7510: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7520: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
7530: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
7540: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
7550: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7560: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
7570: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
7580: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7590: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
75a0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
75b0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
75c0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
75d0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
75e0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
75f0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
7600: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
7610: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
7620: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7630: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
7640: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
7650: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
7660: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
7670: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
7680: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
7690: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
76a0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
76b0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
76c0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
76d0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
76e0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
76f0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7700: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7710: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7720: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7730: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7740: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7750: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7760: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
7770: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7780: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
7790: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
77a0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
77b0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
77c0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
77d0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
77e0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
77f0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7800: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7810: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7820: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7830: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7840: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7850: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7860: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
7870: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
7880: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
7890: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
78a0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
78b0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
78c0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
78d0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
78e0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
78f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7900: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7910: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7920: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7930: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7940: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7950: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7960: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7970: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7980: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
7990: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
79a0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
79b0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
79c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
79d0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
79e0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
79f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7a00: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7a10: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7a20: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7a30: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7a40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7a50: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7a60: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7a70: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7a80: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
7a90: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
7aa0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
7ab0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
7ac0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7ad0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7ae0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7af0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7b00: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7b10: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7b20: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7b30: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7b40: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7b50: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7b60: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7b70: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7b80: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7b90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7ba0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7bb0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7bc0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7bd0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7be0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7bf0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7c00: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7c10: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7c20: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7c30: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7c40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7c50: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7c60: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7c70: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7c80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7c90: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7ca0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7cb0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7cc0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7cd0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7ce0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7cf0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7d00: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7d10: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7d20: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7d30: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7d40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7d50: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7d60: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7d70: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7d80: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7d90: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7da0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7db0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7dc0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7dd0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7de0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7df0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7e00: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7e10: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7e20: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7e30: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7e40: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7e50: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7e60: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7e70: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7e80: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7e90: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7ea0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7eb0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7ec0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7ed0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7ee0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7ef0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7f00: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7f10: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7f20: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7f30: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f40: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7f50: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7f60: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7f70: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7f80: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7f90: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7fa0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7fb0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7fc0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7fd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7fe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7ff0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
8000: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
8010: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
8020: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
8030: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
8040: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
8050: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
8060: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
8070: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
8080: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
8090: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
80a0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
80b0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
80c0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
80d0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
80e0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
80f0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
8100: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
8110: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
8120: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8130: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
8140: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
8150: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
8160: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
8170: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8190: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
81a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
81b0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
81c0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
81d0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
81e0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
81f0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
8200: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
8210: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
8220: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
8230: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
8240: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
8250: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
8260: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
8270: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
8280: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
8290: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
82a0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
82b0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
82c0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
82d0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
82e0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
82f0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
8300: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
8310: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
8320: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
8330: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
8340: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
8350: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
8360: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
8370: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
8380: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
8390: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
83a0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
83b0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
83c0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
83d0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
83e0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
83f0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
8400: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
8410: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
8420: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
8430: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
8440: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
8450: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
8460: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
8470: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
8480: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
8490: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
84a0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
84b0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
84c0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
84d0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
84e0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
84f0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
8500: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
8510: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
8520: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
8530: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
8540: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
8550: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
8560: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
8570: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
8580: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
8590: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
85a0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
85b0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
85c0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
85d0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
85e0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
85f0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
8600: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
8610: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
8620: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8630: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
8640: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
8650: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
8660: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
8670: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
8680: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
8690: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
86a0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
86b0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
86c0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
86d0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
86e0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
86f0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8700: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8710: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8720: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8730: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8740: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8750: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8760: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
8770: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
8780: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
8790: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
87a0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
87b0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
87c0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
87d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
87e0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
87f0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8800: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8810: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8820: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8840: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8860: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8880: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
8890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88a0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
88b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88c0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
88d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88e0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
88f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8900: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8920: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8930: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8940: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8950: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8960: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8970: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8980: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
8990: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
89a0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
89b0: 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c  WHEN_OPEN].** <l
89c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
89d0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
89e0: 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RITE].** <li> [S
89f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8a00: 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TABLE].** <li> [
8a10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
8a20: 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f  CH_ATOMIC].** </
8a30: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8a60: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8a70: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8a80: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8a90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8aa0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8ab0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8ac0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8ad0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8ae0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8af0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8b00: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8b10: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8b20: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8b30: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8b40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8b50: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8b60: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8b70: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8b80: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8b90: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8ba0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8bb0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8bc0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8bd0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8be0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8bf0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8c00: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8c10: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8c20: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8c30: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8c40: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8c50: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8c60: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8c70: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8c80: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
8c90: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
8ca0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
8cb0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
8cc0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
8cd0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
8ce0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8cf0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8d00: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d10: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8d20: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8d30: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8d40: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8d50: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8d60: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8d70: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8d80: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
8d90: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8da0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
8db0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
8dc0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8dd0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
8de0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8df0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8e00: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8e10: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8e20: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8e30: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8e40: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8e50: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8e60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e70: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8e80: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8e90: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8ea0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
8eb0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ec0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
8ed0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
8ee0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8ef0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8f00: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8f10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8f30: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8f40: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8f50: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8f60: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8f70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8f80: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
8f90: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
8fa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8fb0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8fc0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
8fd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fe0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8ff0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
9000: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
9010: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
9020: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
9030: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
9040: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
9050: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
9060: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
9070: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
9080: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
9090: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
90a0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
90b0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
90c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
90d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
90e0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
90f0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
9100: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
9110: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
9120: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9130: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
9140: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
9150: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
9160: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
9170: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
9180: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
9190: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
91a0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
91b0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
91c0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
91d0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
91e0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
91f0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
9200: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
9210: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
9220: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
9230: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
9240: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
9250: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
9260: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
9270: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
9280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9290: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
92a0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
92b0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
92c0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
92d0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
92e0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
92f0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
9300: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
9310: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
9320: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
9330: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
9340: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9350: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
9360: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9370: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
9380: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
9390: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
93a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
93b0: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
93c0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
93d0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
93e0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
93f0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
9400: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
9410: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9420: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
9430: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
9440: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
9450: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
9460: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
9470: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
9480: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
9490: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
94a0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
94b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
94c0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
94d0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
94e0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
94f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
9500: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
9510: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
9520: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
9530: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
9540: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
9550: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
9560: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
9570: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
9580: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9590: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
95a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
95b0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
95c0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
95d0: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
95e0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
95f0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
9600: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9610: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
9620: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
9630: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
9640: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
9650: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
9660: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
9670: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
9680: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
9690: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
96a0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
96b0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
96c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
96d0: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
96e0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
96f0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
9700: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9710: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
9720: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9740: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
9750: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9760: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
9770: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
9780: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
9790: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
97a0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
97b0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
97c0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
97d0: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
97e0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
97f0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
9800: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9810: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
9820: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
9830: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
9840: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
9850: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
9860: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
9870: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
9880: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
9890: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
98a0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
98b0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
98c0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
98d0: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
98e0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
98f0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
9900: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
9910: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
9920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9930: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9940: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9950: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9960: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9970: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9980: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9990: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
99a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
99b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
99c0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
99d0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
99e0: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
99f0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9a00: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
9a10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9a20: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9a30: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9a40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9a50: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
9a60: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9a70: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9a80: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9a90: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9aa0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9ab0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
9ac0: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
9ad0: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
9ae0: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
9af0: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
9b00: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9b10: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9b20: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
9b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b40: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
9b50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b60: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
9b70: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
9b80: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
9b90: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ba0: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
9bb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9bc0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
9bd0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9be0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
9bf0: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
9c00: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9c10: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9c20: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
9c30: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
9c40: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
9c50: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
9c60: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9c70: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
9c80: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
9c90: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
9ca0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
9cb0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9cc0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9cd0: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9ce0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
9cf0: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
9d00: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9d10: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9d20: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
9d30: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
9d40: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
9d50: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
9d60: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
9d70: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
9d80: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
9d90: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
9da0: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
9db0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
9dc0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
9dd0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
9de0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
9df0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
9e00: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9e10: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9e20: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
9e30: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9e40: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9e50: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9e60: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9e70: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
9e80: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9e90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9ea0: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9eb0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9ec0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
9ed0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9ee0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9ef0: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9f00: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9f10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9f20: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9f30: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
9f40: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9f50: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
9f60: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9f70: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9f80: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
9f90: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
9fa0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
9fb0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
9fc0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
9fd0: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
9fe0: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
9ff0: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
a000: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
a010: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
a020: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
a030: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
a040: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
a050: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
a060: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a070: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
a080: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
a090: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
a0a0: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
a0b0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
a0c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
a0d0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
a0e0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
a0f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a100: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
a110: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a120: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a130: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a140: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
a150: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
a160: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
a170: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
a180: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
a190: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
a1a0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
a1b0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
a1c0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
a1d0: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
a1e0: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
a1f0: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
a200: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
a210: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
a220: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
a230: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
a240: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
a250: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
a260: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
a270: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
a280: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
a290: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
a2a0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
a2b0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
a2c0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
a2d0: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
a2e0: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
a2f0: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
a300: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
a310: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
a320: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
a330: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
a340: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
a350: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
a360: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
a370: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
a380: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
a390: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
a3a0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
a3b0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
a3c0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
a3d0: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
a3e0: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
a3f0: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
a400: 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77  teger is the new
a410: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
a420: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
a430: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
a440: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
a450: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
a460: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
a470: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
a480: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
a490: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
a4a0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
a4b0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
a4c0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
a4d0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
a4e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
a4f0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
a500: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
a510: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
a520: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
a530: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
a540: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a550: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
a560: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a570: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
a580: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a590: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a5a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a5b0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
a5c0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
a5d0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
a5e0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
a5f0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
a600: 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61 6e 64  ([WAL file]) and
a610: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 0a 2a   shared memory.*
a620: 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  * files used for
a630: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
a640: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
a650: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
a660: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
a670: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
a680: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
a690: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
a6a0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a6b0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
a6c0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
a6d0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
a6e0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
a6f0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
a700: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
a710: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
a720: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
a730: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
a740: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
a750: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
a760: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
a770: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
a780: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
a790: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
a7a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a7b0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
a7c0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
a7d0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a7e0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a7f0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a800: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a810: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a820: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a830: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a840: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a850: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a860: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a870: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a880: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a890: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a8a0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a8b0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a8c0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a8d0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a8e0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a8f0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a900: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a910: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a920: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a930: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a940: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a950: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a960: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a970: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a980: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a990: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a9a0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a9b0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a9c0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a9d0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a9e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a9f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
aa00: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
aa10: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
aa20: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
aa30: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
aa40: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
aa50: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
aa60: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
aa70: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
aa80: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
aa90: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
aaa0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
aab0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
aac0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
aad0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
aae0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
aaf0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
ab00: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
ab10: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
ab20: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
ab30: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
ab40: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
ab50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab60: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
ab70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
ab80: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
ab90: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
aba0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
abb0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
abc0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
abd0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
abe0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
abf0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
ac00: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
ac10: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
ac20: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
ac30: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
ac40: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
ac50: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
ac60: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
ac70: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
ac80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ac90: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
aca0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
acb0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
acc0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
acd0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
ace0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
acf0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
ad00: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
ad10: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
ad20: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
ad30: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
ad40: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
ad50: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ad60: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ad70: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
ad80: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
ad90: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
ada0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
adb0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
adc0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
add0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
ade0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
adf0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
ae00: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
ae10: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
ae20: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
ae30: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
ae40: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
ae50: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
ae60: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
ae70: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
ae80: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
ae90: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
aea0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
aeb0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
aec0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
aed0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
aee0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
aef0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
af00: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
af10: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
af20: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
af30: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
af40: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
af50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af60: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
af70: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
af80: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
af90: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e  NTER] opcode fin
afa0: 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ds a pointer to 
afb0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a  the top-level.**
afc0: 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74   [VFSes] current
afd0: 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68  ly in use.  ^(Th
afe0: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a  e argument X in.
aff0: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  ** sqlite3_file_
b000: 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54  control(db,SQLIT
b010: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
b020: 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a  TER,X) must be.*
b030: 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69  * of type "[sqli
b040: 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54  te3_vfs] **".  T
b050: 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c  his opcodes will
b060: 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20   set *X.** to a 
b070: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
b080: 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a  op-level VFS.)^.
b090: 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61  ** ^When there a
b0a0: 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20  re multiple VFS 
b0b0: 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61  shims in the sta
b0c0: 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ck, this opcode 
b0d0: 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70  finds the.** upp
b0e0: 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c  er-most shim onl
b0f0: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
b100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b110: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
b120: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
b130: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
b140: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
b150: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
b160: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
b170: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
b180: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b190: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
b1a0: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
b1b0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
b1c0: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
b1d0: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
b1e0: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
b1f0: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
b200: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b210: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b220: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
b230: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
b240: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
b250: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
b260: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
b270: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
b280: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
b290: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
b2a0: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
b2b0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
b2c0: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
b2d0: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
b2e0: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
b2f0: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
b300: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
b310: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b320: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
b330: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
b340: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
b350: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
b360: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
b370: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
b380: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b390: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
b3a0: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
b3b0: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
b3c0: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
b3d0: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
b3e0: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
b3f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
b400: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
b410: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
b420: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b430: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b440: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
b450: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b460: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
b470: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
b480: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
b490: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b4a0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b4b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b4c0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
b4d0: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
b4e0: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
b4f0: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
b500: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
b510: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
b520: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
b530: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
b540: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
b550: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
b560: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
b570: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
b580: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
b590: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
b5a0: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
b5b0: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
b5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b5d0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b5e0: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
b5f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
b600: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
b610: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
b620: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
b630: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
b640: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
b650: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
b660: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
b670: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
b680: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
b690: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
b6a0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
b6b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b6c0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b6d0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
b6e0: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
b6f0: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
b700: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
b710: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
b720: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
b730: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
b740: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
b750: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b760: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b770: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
b780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b790: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b7a0: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b7b0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b7c0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b7d0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b7e0: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b7f0: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b800: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b810: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b820: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b830: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b840: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b850: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b860: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b870: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b880: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b890: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b8a0: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b8b0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b8c0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b8d0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b8e0: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b8f0: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b900: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b910: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b920: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b930: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b940: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b950: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b960: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b970: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b980: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b990: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b9a0: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b9b0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b9c0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b9d0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b9e0: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b9f0: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
ba00: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
ba10: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba20: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
ba30: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
ba40: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
ba50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ba60: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
ba70: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
ba80: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
ba90: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
baa0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
bab0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
bac0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
bad0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
bae0: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
baf0: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
bb00: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
bb10: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
bb20: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
bb30: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
bb40: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
bb50: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
bb60: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
bb70: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
bb80: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
bb90: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
bba0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
bbb0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
bbc0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
bbd0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
bbe0: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
bbf0: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
bc00: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bc10: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
bc20: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
bc40: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
bc50: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
bc60: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
bc70: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
bc80: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
bc90: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
bca0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
bcb0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
bcc0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
bcd0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
bce0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
bcf0: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
bd00: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
bd10: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
bd20: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
bd30: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
bd40: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
bd50: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
bd60: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
bd70: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
bd80: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
bd90: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
bda0: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
bdb0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
bdc0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
bdd0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
bde0: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
bdf0: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
be00: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
be10: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
be20: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
be30: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
be40: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
be50: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
be60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
be70: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
be80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
be90: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
bea0: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
beb0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
bec0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
bed0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
bee0: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
bef0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
bf00: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
bf10: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
bf20: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
bf30: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
bf40: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
bf50: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
bf60: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
bf70: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
bf80: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
bf90: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
bfa0: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
bfb0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
bfc0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bfd0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
bfe0: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
bff0: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
c000: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
c010: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
c020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c030: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
c040: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
c050: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
c060: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
c070: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
c080: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
c090: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
c0a0: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
c0b0: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
c0c0: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
c0d0: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
c0e0: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
c0f0: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
c100: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
c110: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
c120: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
c130: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c140: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
c150: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
c160: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c170: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c180: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
c190: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
c1a0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
c1b0: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c1c0: 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  dle associated w
c1d0: 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c  ith a file handl
c1e0: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a  e.  This file.**
c1f0: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
c200: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
c210: 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   as a pointer to
c220: 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68   a native file h
c230: 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69  andle and.** wri
c240: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e  tes the resultin
c250: 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a  g value there..*
c260: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c270: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
c280: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
c290: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c2a0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c2b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
c2c0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
c2d0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
c2e0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
c2f0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
c300: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
c310: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
c320: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
c330: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
c340: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
c350: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
c360: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
c370: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
c380: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
c390: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
c3a0: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
c3b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c3c0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c3d0: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
c3e0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c3f0: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
c400: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
c410: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
c420: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
c430: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
c440: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
c450: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
c460: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
c470: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
c480: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
c490: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
c4a0: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
c4b0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
c4c0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
c4d0: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
c4e0: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
c4f0: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
c500: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
c510: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
c520: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
c530: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c540: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
c550: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c560: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
c570: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c580: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
c590: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
c5a0: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c5b0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c5c0: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
c5d0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
c5e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c5f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c600: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
c610: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
c620: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
c630: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
c640: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
c650: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
c660: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
c670: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c680: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
c690: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a   opcode.  .**.**
c6a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c6b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c6c0: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74  _WRITE]].** If t
c6d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c6e0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c6f0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75  ITE] opcode retu
c700: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74  rns SQLITE_OK, t
c710: 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20  hen.** the file 
c720: 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c  descriptor is pl
c730: 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20 77  aced in "batch w
c740: 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63  rite mode", whic
c750: 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73  h.** means all s
c760: 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20  ubsequent write 
c770: 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20  operations will 
c780: 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64 20  be deferred and 
c790: 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c  done.** atomical
c7a0: 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b  ly at the next [
c7b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c7c0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c7d0: 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74  ].  Systems.** t
c7e0: 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  hat do not suppo
c7f0: 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20  rt batch atomic 
c800: 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75  writes will retu
c810: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c820: 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e  ND..** ^Followin
c830: 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 53  g a successful S
c840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c850: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61  N_ATOMIC_WRITE a
c860: 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74  nd prior to.** t
c870: 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49  he closing [SQLI
c880: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c890: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72  ATOMIC_WRITE] or
c8a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c8b0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c8c0: 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65  C_WRITE], SQLite
c8d0: 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f   will make.** no
c8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 63   VFS interface c
c8f0: 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  alls on the same
c900: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c910: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a  file descriptor.
c920: 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63 61  ** except for ca
c930: 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69 74  lls to the xWrit
c940: 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65  e method and the
c950: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c960: 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51  thod.** with [SQ
c970: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
c980: 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  HINT]..**.** <li
c990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c9a0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c9b0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
c9c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c9d0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
c9e0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
c9f0: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
ca00: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
ca10: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
ca20: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
ca30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
ca40: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca50: 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65  ] to be performe
ca60: 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a  d atomically..**
ca70: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
ca80: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ca90: 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e  TE_OK] if and on
caa0: 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65 73  ly if the writes
cab0: 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72   were.** all per
cac0: 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66 75  formed successfu
cad0: 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65 65  lly and have bee
cae0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70  n committed to p
caf0: 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67  ersistent storag
cb00: 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  e..** ^Regardles
cb10: 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
cb20: 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65 73  not it is succes
cb30: 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20  sful, this file 
cb40: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a  control takes.**
cb50: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
cb60: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
cb70: 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20  h write mode so 
cb80: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
cb90: 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65  ent.** write ope
cba0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
cbb0: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
cbc0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
cbd0: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
cbe0: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
cbf0: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
cc00: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
cc10: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
cc20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cc30: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
cc40: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cc50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cc60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  K_ATOMIC_WRITE]]
cc70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cc80: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cc90: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
cca0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
ccb0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
ccc0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
ccd0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
cce0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
ccf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cd00: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
cd10: 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  o be rolled back
cd20: 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20  ..** ^This file 
cd30: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68  control takes th
cd40: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
cd50: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
cd60: 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20  rite mode.** so 
cd70: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
cd80: 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74  ent write operat
cd90: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
cda0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
cdb0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cdc0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cdd0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
cde0: 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a  WRITE without.**
cdf0: 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
ce00: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c  ful call to [SQL
ce10: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
ce20: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
ce30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d  E_FCNTL_LOCK_TIM
ce50: 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  EOUT]].** The [S
ce60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
ce70: 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65  _TIMEOUT] opcode
ce80: 20 63 61 75 73 65 73 20 61 74 74 65 6d 70 74 73   causes attempts
ce90: 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20   to obtain.** a 
cea0: 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20  file lock using 
ceb0: 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68  the xLock or xSh
cec0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66  mLock methods of
ced0: 20 74 68 65 20 56 46 53 20 74 6f 20 77 61 69 74   the VFS to wait
cee0: 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d 20  .** for up to M 
cef0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
cf00: 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77 68 65  ore failing, whe
cf10: 72 65 20 4d 20 69 73 20 74 68 65 20 73 69 6e 67  re M is the sing
cf20: 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20  le .** unsigned 
cf30: 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 74 65  integer paramete
cf40: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
cf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41  QLITE_FCNTL_DATA
cf60: 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68  _VERSION]].** Th
cf70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cf80: 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70  DATA_VERSION] op
cf90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
cfa0: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
cfb0: 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73 65 20  o.** a database 
cfc0: 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67 75 6d  file.  The argum
cfd0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
cfe0: 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75 6e 73   to a 32-bit uns
cff0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
d000: 2a 20 54 68 65 20 22 64 61 74 61 20 76 65 72 73  * The "data vers
d010: 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70 61 67  ion" for the pag
d020: 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  er is written in
d030: 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72 2e 20  to the pointer. 
d040: 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20 76 65   The.** "data ve
d050: 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73 20 77  rsion" changes w
d060: 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68 61 6e  henever any chan
d070: 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74 68 65  ge occurs to the
d080: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
d090: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  * database file,
d0a0: 20 65 69 74 68 65 72 20 74 68 72 6f 75 67 68 20   either through 
d0b0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
d0c0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
d0d0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
d0e0: 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74 72 61  n or through tra
d0f0: 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74  nsactions commit
d100: 74 65 64 20 62 79 20 73 65 70 61 72 61 74 65 20  ted by separate 
d110: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
d120: 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79  ections possibly
d130: 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73   in other proces
d140: 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 74 65  ses. The [sqlite
d150: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d160: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
d170: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
d180: 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74 61 62  ind if any datab
d190: 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65  ase on the conne
d1a0: 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e 67 65  ction has change
d1b0: 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 20 69  d,.** but that i
d1c0: 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 64  nterface respond
d1d0: 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20  s to changes on 
d1e0: 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 73 20  TEMP as well as 
d1f0: 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a  MAIN and does.**
d200: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 6d   not provide a m
d210: 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74 65  echanism to dete
d220: 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20 4d 41  ct changes to MA
d230: 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20  IN only.  Also, 
d240: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
d250: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
d260: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d270: 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  nds to internal 
d280: 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64  changes only and
d290: 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e 67 65  .** omits change
d2a0: 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65 72 20  s made by other 
d2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d2c0: 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50  ions.  The.** [P
d2d0: 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69  RAGMA data_versi
d2e0: 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76  on] command prov
d2f0: 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20  ide a mechanism 
d300: 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  to detect change
d310: 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  s to.** a single
d320: 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
d330: 73 65 20 74 68 61 74 20 6f 63 63 75 72 20 64 75  se that occur du
d340: 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74 61 62  e to other datab
d350: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c  ase connections,
d360: 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 63 68  .** but omits ch
d370: 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65  anges implemente
d380: 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
d390: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e 20  e connection on 
d3a0: 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a 20 63  which it is.** c
d3b0: 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 69 6c  alled.  This fil
d3c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65  e control is the
d3d0: 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20   only mechanism 
d3e0: 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  to detect change
d3f0: 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e  s that.** happen
d400: 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c   either internal
d410: 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79  ly or externally
d420: 20 61 6e 64 20 74 68 61 74 20 61 72 65 20 61 73   and that are as
d430: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
d440: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 74   a particular at
d450: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2e  tached database.
d460: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
d470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d480: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
d490: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
d4a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d4b0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
d4c0: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
d4d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d4e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d4f0: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
d500: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d510: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
d520: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
d530: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
d540: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
d550: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
d560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
d570: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
d580: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
d590: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
d5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
d5b0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
d5c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
d5d0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
d5e0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
d5f0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d600: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
d610: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
d620: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
d630: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
d640: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
d650: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
d660: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
d670: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d680: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
d690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
d6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d6b0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
d6c0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
d6d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d6e0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
d700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d710: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
d720: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
d730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d740: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
d750: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
d760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d770: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
d780: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
d790: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d7a0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
d7b0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
d7c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d7d0: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
d7e0: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
d7f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d800: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
d810: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
d820: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
d830: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
d840: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
d850: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d860: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
d870: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
d880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
d890: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
d8a0: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
d8b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
d8c0: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
d8d0: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
d8e0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
d8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d900: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
d910: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
d920: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
d930: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
d940: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
d950: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
d960: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d970: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
d980: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
d990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d9a0: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
d9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
d9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d9d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
d9e0: 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23  C_WRITE     31.#
d9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
da00: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
da10: 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64  C_WRITE    32.#d
da20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da30: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
da40: 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65  IC_WRITE  33.#de
da50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
da60: 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20  L_LOCK_TIMEOUT  
da70: 20 20 20 20 20 20 20 20 20 33 34 0a 23 64 65 66           34.#def
da80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da90: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20 20 20  _DATA_VERSION   
daa0: 20 20 20 20 20 20 20 20 33 35 0a 0a 2f 2a 20 64          35../* d
dab0: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
dac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dad0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
dae0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
daf0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
db00: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
db10: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
db20: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
db30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
db40: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
db50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
db60: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
db70: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
db80: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
db90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
dba0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
dbb0: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
dbc0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
dbd0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
dbe0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
dbf0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
dc00: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
dc10: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
dc20: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
dc30: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
dc40: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
dc50: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
dc60: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
dc70: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
dc80: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
dc90: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
dca0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
dcb0: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
dcc0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
dcd0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
dce0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
dcf0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
dd00: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
dd10: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
dd20: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
dd30: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
dd40: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
dd50: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
dd60: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
dd70: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
dd80: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
dd90: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
dda0: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
ddb0: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
ddc0: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
ddd0: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
dde0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
ddf0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
de00: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
de10: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
de20: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
de30: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
de40: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
de50: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
de60: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
de70: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
de80: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
de90: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
dea0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
deb0: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
dec0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
ded0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
dee0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
def0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
df00: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
df10: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
df20: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
df30: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
df40: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
df50: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
df60: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
df70: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
df80: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
df90: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
dfa0: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
dfb0: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78   is sometimes ex
dfc0: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67  tended by adding
dfd0: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74   new methods ont
dfe0: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45  o.** the end.  E
dff0: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e  ach time such an
e000: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72   extension occur
e010: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  s, the iVersion 
e020: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72  field.** is incr
e030: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56  emented.  The iV
e040: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61  ersion value sta
e050: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e  rted out as 1 in
e060: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e070: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64  ion 3.5.0] on [d
e080: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68  ateof:3.5.0], th
e090: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20  en increased to 
e0a0: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65  2.** with SQLite
e0b0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d   [version 3.7.0]
e0c0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
e0d0: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63  0], and then inc
e0e0: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77  reased.** to 3 w
e0f0: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73  ith SQLite [vers
e100: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64  ion 3.7.6] on [d
e110: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41  ateof:3.7.6].  A
e120: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
e130: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e  .** may be appen
e140: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ded to the sqlit
e150: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e  e3_vfs object an
e160: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  d the iVersion v
e170: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72  alue.** may incr
e180: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75  ease again in fu
e190: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e1a0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65   SQLite..** Note
e1b0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
e1c0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
e1d0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
e1e0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
e1f0: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a  transition from.
e200: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
e210: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65  on 3.5.9] to [ve
e220: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20  rsion 3.6.0] on 
e230: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a  [dateof:3.6.0].*
e240: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  * and yet the iV
e250: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
e260: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a   not modified..*
e270: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e280: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e290: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e2a0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e2b0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e2c0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e2d0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e2e0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e2f0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e300: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e310: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e320: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e330: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e340: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e350: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e360: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e370: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e380: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e390: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e3a0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e3b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e3c0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e3d0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e3e0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e3f0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e400: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e410: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e420: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e430: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e440: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e450: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e460: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e470: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e480: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e490: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e4a0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e4b0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e4c0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e4d0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e4e0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e4f0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e500: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e510: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e520: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e530: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e540: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e550: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e560: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e570: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e580: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e590: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e5a0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e5b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e5c0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e5d0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e5e0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e5f0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e600: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e610: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e620: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e630: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e640: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e650: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e660: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e670: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
e680: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
e690: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
e6a0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
e6b0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
e6c0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
e6d0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
e6e0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
e6f0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
e700: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
e710: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
e720: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
e730: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
e740: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
e750: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
e760: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
e770: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
e780: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
e790: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
e7a0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
e7b0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
e7c0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
e7d0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
e7e0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
e7f0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
e800: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
e810: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
e820: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
e830: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
e840: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
e850: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
e860: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
e870: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
e880: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
e890: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
e8a0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
e8b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e8c0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
e8d0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
e8e0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
e8f0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
e900: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
e910: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
e920: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
e930: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
e940: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
e950: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
e960: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
e970: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e980: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
e990: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
e9a0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
e9b0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
e9c0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
e9d0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
e9e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
e9f0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ea00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ea10: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
ea20: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
ea30: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
ea40: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
ea50: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
ea60: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
ea70: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
ea80: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
ea90: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
eaa0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
eab0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
eac0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ead0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
eae0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
eaf0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
eb00: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
eb10: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
eb20: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
eb30: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
eb40: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
eb50: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
eb60: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
eb70: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
eb80: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
eb90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eba0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
ebb0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ebc0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
ebd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ebe0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
ebf0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ec00: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
ec10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ec20: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
ec30: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
ec40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
ec50: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ec60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
ec70: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
ec80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ec90: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
eca0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
ecb0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
ecc0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
ecd0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
ece0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
ecf0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
ed00: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
ed10: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
ed20: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
ed30: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
ed40: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
ed50: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
ed60: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
ed70: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
ed80: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
ed90: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
eda0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
edb0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
edc0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
edd0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
ede0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
edf0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
ee00: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
ee10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
ee20: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
ee30: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
ee40: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
ee50: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
ee60: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
ee70: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
ee80: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
ee90: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
eea0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
eeb0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
eec0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
eed0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
eee0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
eef0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
ef00: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
ef10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ef20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ef30: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
ef40: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
ef50: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
ef60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
ef70: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
ef80: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
ef90: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
efa0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
efb0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
efc0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
efd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
efe0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
eff0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f000: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f010: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f020: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f030: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f040: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f060: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f070: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f080: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f090: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f0a0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f0b0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f0c0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f0d0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f0e0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f0f0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f100: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f110: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f120: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f130: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f140: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f150: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f160: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f170: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f180: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f190: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f1a0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f1b0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f1c0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f1d0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f1e0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f1f0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f200: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f210: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f220: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f230: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f240: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f250: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f260: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f280: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f290: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f2a0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f2b0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f2c0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f2d0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f2e0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f2f0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f300: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f310: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f320: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f330: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f340: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f350: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f360: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f370: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f380: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f390: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f3a0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f3b0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f3c0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f3d0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f3e0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f3f0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f400: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f410: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f420: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f430: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f440: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f450: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f460: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f470: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f480: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f490: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f4a0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f4b0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f4c0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f4d0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f4e0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f4f0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f500: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f510: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f520: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f530: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f540: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f550: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f560: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f570: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f580: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f590: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f5a0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f5b0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f5c0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f5d0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f5e0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f5f0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f600: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f610: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f620: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f630: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f640: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f650: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f660: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f670: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
f680: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
f690: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
f6a0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
f6b0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
f6c0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
f6d0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
f6e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
f6f0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
f700: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
f710: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
f720: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
f730: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
f740: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
f750: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
f760: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
f770: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
f780: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f790: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
f7a0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
f7b0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
f7c0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
f7d0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
f7e0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
f7f0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
f800: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
f810: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
f820: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
f830: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
f840: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
f850: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
f860: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
f870: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
f880: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
f890: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
f8a0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
f8b0: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
f8c0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
f8d0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
f8e0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
f8f0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
f900: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
f910: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
f920: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
f930: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
f940: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
f950: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
f960: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
f970: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
f980: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
f990: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
f9a0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
f9b0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
f9c0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
f9d0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
f9e0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
f9f0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fa00: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fa10: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fa20: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fa30: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fa40: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fa50: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fa60: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fa70: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fa80: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fa90: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
faa0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fab0: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fac0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fad0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fae0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
faf0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fb00: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fb10: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fb20: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
fb30: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fb40: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fb50: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fb60: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
fb70: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
fb80: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
fb90: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
fba0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
fbb0: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
fbc0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
fbd0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
fbe0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
fbf0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
fc00: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
fc10: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
fc20: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
fc30: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
fc40: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
fc50: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
fc60: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
fc70: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
fc80: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
fc90: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
fca0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
fcb0: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
fcc0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
fcd0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
fce0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
fcf0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
fd00: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
fd10: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
fd20: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
fd30: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
fd40: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
fd50: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
fd60: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
fd70: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
fd80: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
fd90: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
fda0: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
fdb0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
fdc0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
fdd0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
fde0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
fdf0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
fe00: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
fe10: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
fe20: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
fe30: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
fe40: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
fe50: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
fe60: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
fe70: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
fe80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
fe90: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
fea0: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
feb0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
fec0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
fed0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
fee0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
fef0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
ff00: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
ff10: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
ff20: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
ff30: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
ff40: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
ff50: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
ff60: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
ff70: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
ff80: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
ff90: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
ffa0: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
ffb0: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
ffc0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
ffd0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
ffe0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
fff0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
10000 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
10010 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
10020 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10030 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
10040 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
10050 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
10060 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
10070 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
10080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10090 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
100a0 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
100b0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
100c0 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
100d0 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
100e0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
100f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10100 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
10110 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
10120 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10130 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10140 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10150 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
10160 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
10170 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10190 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
101a0 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
101b0 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
101c0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
101d0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
101e0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
101f0 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
10200 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10210 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
10220 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
10230 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
10240 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
10250 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
10260 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
10270 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
10280 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
10290 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
102a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
102b0 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
102c0 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
102d0 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
102e0 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
102f0 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
10300 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
10310 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
10320 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
10330 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
10340 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
10350 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
10360 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
10370 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10380 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
10390 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
103a0 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
103b0 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
103c0 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
103d0 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
103e0 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
103f0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10400 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10410 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
10420 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10430 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10440 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
10450 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
10460 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10470 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
10480 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
10490 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
104a0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
104b0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
104c0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
104d0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
104e0 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
104f0 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
10500 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
10510 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10520 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10530 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
10540 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
10550 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
10560 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10570 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
10580 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10590 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
105a0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
105b0 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
105c0 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
105d0 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
105e0 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
105f0 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
10600 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
10610 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
10620 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
10630 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
10640 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
10650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10660 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
10670 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10680 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10690 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
106a0 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
106b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
106c0 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
106d0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
106e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
106f0 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
10700 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
10710 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10720 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10730 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10740 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10750 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10760 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10770 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10780 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10790 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
107a0 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
107b0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
107c0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
107d0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
107e0 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
107f0 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
10800 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
10810 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10820 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10830 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10840 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10850 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10860 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10870 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10880 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10890 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
108a0 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
108b0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
108c0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
108d0 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
108e0 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
108f0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10900 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10910 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10920 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10930 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10940 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10950 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10960 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10970 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10980 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10990 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
109a0 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
109b0 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
109c0 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
109d0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
109e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
109f0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10a00 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10a10 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10a20 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10a30 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10a40 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10a50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10a60 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10a70 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10a80 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10a90 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10aa0 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10ab0 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10ac0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10ad0 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10ae0 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10af0 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10b00 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10b10 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10b20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10b30 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10b40 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10b50 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10b60 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10b70 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10b80 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10b90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10ba0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10bb0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10bc0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10bd0 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10be0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10bf0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10c00 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10c10 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10c20 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10c30 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10c40 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10c50 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10c60 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10c70 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10c80 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10c90 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10ca0 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10cb0 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
10cc0 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
10cd0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
10ce0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
10cf0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
10d00 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10d10 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
10d20 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
10d30 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
10d40 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
10d50 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
10d60 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
10d70 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
10d80 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10d90 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
10da0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
10db0 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
10dc0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
10dd0 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
10de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10df0 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
10e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10e10 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
10e20 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
10e30 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10e40 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
10e50 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
10e60 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
10e70 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
10e80 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
10e90 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
10ea0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
10eb0 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
10ec0 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
10ed0 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
10ee0 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
10ef0 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
10f00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10f10 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
10f20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
10f30 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
10f40 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
10f50 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
10f60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10f70 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
10f80 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
10f90 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
10fa0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
10fb0 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
10fc0 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
10fd0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
10fe0 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
10ff0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
11000 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
11010 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11020 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
11030 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
11040 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
11050 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
11060 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
11070 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
11080 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
11090 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
110a0 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
110b0 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
110c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
110d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
110e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
110f0 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
11100 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11110 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
11120 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11130 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11140 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
11150 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
11160 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
11170 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
11180 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11190 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
111a0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
111b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
111c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
111d0 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
111e0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
111f0 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
11200 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
11210 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
11220 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
11230 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
11240 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11250 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11260 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11270 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
11280 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
11290 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
112a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
112b0 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
112c0 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
112d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
112e0 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
112f0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
11300 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11310 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
11320 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
11330 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
11340 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
11350 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
11360 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
11370 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
11380 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11390 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
113a0 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
113b0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
113c0 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
113d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
113e0 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
113f0 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
11400 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
11410 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
11420 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
11430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
11440 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
11450 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
11460 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
11470 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
11480 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
11490 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
114a0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
114b0 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
114c0 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
114d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
114e0 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
114f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11500 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
11510 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
11520 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
11530 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
11540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11550 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11560 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11570 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11580 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
11590 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
115a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
115b0 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
115c0 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
115d0 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
115e0 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
115f0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
11600 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
11610 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
11620 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
11630 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
11640 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
11650 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
11660 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11670 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11680 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11690 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
116a0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
116b0 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
116c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
116d0 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
116e0 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
116f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11700 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
11710 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11720 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11730 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11740 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11750 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11760 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11770 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11780 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11790 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
117a0 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
117b0 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
117c0 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
117d0 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
117e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
117f0 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
11800 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11810 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11820 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11830 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11840 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11850 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11860 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11870 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11880 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11890 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
118a0 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
118b0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
118c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
118d0 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
118e0 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
118f0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11900 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11910 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11920 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11930 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11940 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11950 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11960 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11970 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11980 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11990 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
119a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
119b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
119c0 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
119d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
119e0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
119f0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11a00 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11a10 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11a20 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11a30 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11a40 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11a50 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11a60 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11a70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11a80 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11a90 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11aa0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11ab0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11ac0 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11ad0 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11ae0 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11af0 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11b00 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11b10 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11b20 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11b30 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11b40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11b50 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11b60 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11b70 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11b80 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11b90 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11ba0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11bb0 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11bc0 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11bd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11be0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11bf0 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11c00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11c10 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11c20 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11c30 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11c40 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11c50 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11c60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11c70 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11c80 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11c90 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11ca0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11cb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11cc0 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
11cd0 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
11ce0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
11cf0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11d00 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
11d10 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
11d20 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
11d30 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
11d40 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
11d50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
11d60 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11d70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11d80 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
11d90 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11da0 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
11db0 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
11dc0 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
11dd0 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
11de0 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
11df0 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
11e00 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
11e10 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
11e20 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
11e30 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
11e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11e50 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
11e60 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
11e70 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
11e80 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11e90 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11ea0 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
11eb0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
11ec0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
11ed0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
11ee0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
11ef0 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
11f00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
11f10 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
11f20 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
11f30 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
11f40 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
11f50 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
11f60 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
11f70 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11f80 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
11f90 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
11fa0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
11fb0 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
11fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11fd0 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
11fe0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
11ff0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
12000 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12010 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12020 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
12030 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
12040 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
12050 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
12060 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
12070 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
12080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
12090 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
120a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
120b0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
120c0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
120d0 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
120e0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
120f0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
12100 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
12110 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
12120 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
12130 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
12140 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
12150 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12160 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12170 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
12180 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12190 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
121a0 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
121b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
121c0 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
121d0 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
121e0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
121f0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
12200 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
12210 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12220 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
12230 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
12240 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
12250 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
12260 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
12270 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12280 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
12290 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
122a0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
122b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
122c0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
122d0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
122e0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
122f0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
12300 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
12310 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
12320 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
12330 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
12340 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
12350 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
12360 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
12370 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
12380 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
12390 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
123a0 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
123b0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
123c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
123d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
123e0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
123f0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
12400 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
12410 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
12420 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
12430 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
12440 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
12450 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
12460 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
12470 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
12480 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12490 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
124a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
124b0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
124c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
124d0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
124e0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
124f0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
12500 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
12510 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
12520 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
12530 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
12540 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
12550 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12560 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
12570 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
12580 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
12590 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
125a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
125b0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
125c0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
125d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
125e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
125f0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
12600 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
12610 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
12620 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12630 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
12640 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
12650 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
12660 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
12670 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
12680 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
12690 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
126a0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
126b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
126c0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
126d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
126e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
126f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
12700 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12710 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
12720 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
12730 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12740 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
12750 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
12760 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12770 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12780 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
127a0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
127b0 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
127c0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
127d0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
127e0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
127f0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
12800 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
12810 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
12820 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
12830 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
12840 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
12850 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
12860 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
12870 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12880 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12890 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
128a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
128b0 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
128c0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
128d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
128e0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
128f0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
12900 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
12910 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12920 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12930 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
12940 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
12950 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
12960 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12970 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12980 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12990 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
129a0 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
129b0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
129c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
129d0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
129e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
129f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
12a00 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
12a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12a20 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
12a30 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
12a40 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12a50 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
12a60 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12a70 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12a80 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12a90 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12aa0 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12ab0 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12ac0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12ad0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12ae0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
12af0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
12b00 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
12b10 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
12b20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
12b30 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
12b40 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
12b50 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
12b60 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12b70 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12b80 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12b90 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12ba0 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12bb0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12bc0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12bd0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
12be0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
12bf0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
12c00 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
12c10 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
12c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12c30 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
12c40 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
12c50 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
12c60 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
12c70 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12c80 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
12c90 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12ca0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
12cb0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
12cc0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
12cd0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
12ce0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
12cf0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
12d00 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
12d10 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
12d20 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
12d30 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
12d40 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
12d50 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
12d60 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
12d70 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
12d80 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
12d90 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
12da0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12db0 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
12dc0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12dd0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12de0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
12df0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
12e00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
12e10 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
12e20 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
12e30 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
12e40 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
12e50 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
12e60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12e70 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
12e80 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
12e90 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
12ea0 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
12eb0 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
12ec0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
12ed0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
12ee0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
12ef0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
12f00 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
12f10 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
12f20 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
12f30 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
12f40 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
12f50 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
12f60 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
12f70 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
12f80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12f90 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
12fa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12fb0 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
12fc0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
12fd0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
12fe0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12ff0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
13000 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
13010 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
13020 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
13030 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
13040 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
13050 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13060 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
13070 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
13080 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
13090 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
130a0 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
130b0 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
130c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
130d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
130e0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
130f0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
13100 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
13110 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13120 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
13130 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
13140 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
13150 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
13160 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
13170 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
13180 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
13190 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
131a0 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
131b0 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
131c0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
131d0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
131e0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
131f0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
13200 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
13210 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
13220 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
13230 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13240 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
13250 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
13260 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
13270 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
13280 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
13290 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
132a0 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
132b0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
132c0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
132d0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
132e0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
132f0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
13300 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
13310 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13320 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
13330 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
13340 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
13350 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
13360 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
13370 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
13380 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
13390 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
133a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
133b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
133c0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
133d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
133e0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
133f0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
13400 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
13410 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
13420 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
13430 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
13440 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
13450 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13460 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
13470 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
13480 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
13490 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
134a0 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
134b0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
134c0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
134d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
134e0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
134f0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
13500 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
13510 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
13520 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
13530 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
13540 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
13550 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13560 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
13570 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
13580 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13590 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
135a0 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
135b0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
135c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
135d0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
135e0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
135f0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
13600 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
13610 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
13620 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
13630 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
13640 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13650 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
13660 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13670 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
13680 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
13690 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
136a0 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
136b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
136c0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
136d0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
136e0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
136f0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
13700 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
13710 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13720 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13730 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13740 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13750 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13760 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13770 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13780 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
137a0 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
137b0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
137c0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
137d0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
137e0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
137f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
13800 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13810 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
13820 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13830 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13840 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13850 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13860 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13870 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13880 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13890 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
138a0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
138b0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
138c0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
138d0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
138e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
138f0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13900 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13910 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13920 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13930 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13940 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13950 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13960 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13970 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13980 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13990 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
139a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
139b0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
139c0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
139d0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
139e0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
139f0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
13a00 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13a10 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
13a20 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
13a30 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13a40 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13a50 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13a60 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13a70 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13a80 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13a90 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13aa0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13ab0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13ac0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13ad0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
13ae0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13af0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13b00 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
13b10 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
13b20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
13b30 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13b40 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13b50 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13b60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13b70 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13b80 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13b90 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13ba0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13bb0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13bc0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13bd0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
13be0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
13bf0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
13c00 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
13c10 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
13c20 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
13c30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13c40 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
13c50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13c60 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13c70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13c80 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13c90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13ca0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13cb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13cc0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
13cd0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ce0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
13cf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13d00 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13d10 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13d20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13d30 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13d40 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
13d50 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
13d60 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13d70 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13d80 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13da0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13db0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
13dc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13dd0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
13de0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
13df0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
13e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e10 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
13e20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
13e30 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
13e40 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
13e50 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
13e60 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
13e70 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
13e80 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
13e90 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
13ea0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
13eb0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
13ec0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
13ed0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13ee0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
13ef0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
13f00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13f10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13f20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13f30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13f40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13f50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13f60 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13f70 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
13f80 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
13f90 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13fb0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13fc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13fd0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
13fe0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
13ff0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
14000 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14010 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
14020 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14030 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
14040 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14050 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
14060 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14070 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14080 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14090 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
140a0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
140b0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
140c0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
140d0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
140e0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
140f0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
14100 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
14110 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
14120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14130 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
14140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14150 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
14160 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
14170 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
14180 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
14190 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
141a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
141b0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
141c0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
141d0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
141e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
141f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14200 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
14210 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
14220 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
14230 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
14240 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
14250 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14260 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
14270 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
14280 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
14290 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
142a0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
142b0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
142c0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
142d0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
142e0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
142f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
14300 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14310 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
14320 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
14330 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
14340 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
14350 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
14360 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14370 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
14380 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14390 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143a0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
143b0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
143c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
143d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
143e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
143f0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
14400 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
14410 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14420 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14430 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14440 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14450 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14460 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14470 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14480 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14490 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
144a0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
144b0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
144c0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
144d0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
144e0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
144f0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
14500 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
14510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14520 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14530 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
14540 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
14550 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
14560 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
14570 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14580 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14590 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
145a0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
145b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
145c0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
145d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
145e0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
145f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14600 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
14610 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14630 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
14640 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14650 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14660 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14670 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14680 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14690 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
146a0 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
146b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
146c0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
146d0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
146e0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
146f0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
14700 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
14710 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
14720 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
14730 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14740 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14750 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14760 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14770 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14780 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14790 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
147a0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
147b0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
147c0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
147d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
147e0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  SMALL_MALLOC]] <
147f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14800 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64  _SMALL_MALLOC</d
14810 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14830 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  ALL_MALLOC optio
14840 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14850 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79  rgument of.** ty
14860 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
14870 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14880 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20  , which if true 
14890 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20  provides a hint 
148a0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61  to.** SQLite tha
148b0 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69  t it should avoi
148c0 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  d large memory a
148d0 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f  llocations if po
148e0 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74  ssible..** SQLit
148f0 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65  e will run faste
14900 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20  r if it is free 
14910 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65  to make large me
14920 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14930 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70  ,.** but some ap
14940 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
14950 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c  prefer to run sl
14960 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65  ower in exchange
14970 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65   for.** guarante
14980 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20  es about memory 
14990 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68  fragmentation th
149a0 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20  at are possible 
149b0 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f  if large.** allo
149c0 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69  cations are avoi
149d0 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ded.  This hint 
149e0 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e  is normally off.
149f0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14a00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14a10 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
14a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14a30 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
14a40 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14a50 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14a60 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14a70 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14a80 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14a90 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14aa0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14ab0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14ac0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14ad0 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
14ae0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14af0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14b10 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
14b20 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
14b30 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
14b40 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
14b50 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
14b60 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14b70 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14b80 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14b90 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14ba0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14bb0 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14bc0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14bd0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
14be0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14bf0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
14c00 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
14c10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14c20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
14c30 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
14c40 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
14c50 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
14c60 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14c70 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14c80 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14c90 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14ca0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14cb0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14cc0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14cd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14ce0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
14cf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14d00 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
14d10 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14d20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14d30 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  H option is no l
14d40 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c  onger used..** <
14d50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14d60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14d70 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14d80 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14d90 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14da0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14db0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
14dc0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14dd0 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
14de0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
14df0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
14e00 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
14e10 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
14e20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
14e30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
14e40 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
14e50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
14e60 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
14e70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14e80 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
14e90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
14ea0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
14eb0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
14ec0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
14ed0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14ee0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
14ef0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14f00 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
14f10 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
14f20 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
14f30 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
14f40 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
14f50 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
14f60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
14f70 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
14f80 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
14f90 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
14fa0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
14fb0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
14fc0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
14fd0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
14fe0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
14ff0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
15000 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
15010 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
15020 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15030 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15040 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15050 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15060 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
15070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15080 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
15090 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
150a0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
150b0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
150c0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
150d0 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
150e0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
150f0 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
15100 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
15110 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
15120 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
15130 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
15140 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
15150 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
15160 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
15170 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
15180 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
15190 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
151a0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
151b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
151c0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
151d0 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
151e0 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
151f0 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
15200 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
15210 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
15220 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
15230 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
15240 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
15250 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
15260 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
15270 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
15280 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
15290 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
152a0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
152b0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
152c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
152d0 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
152e0 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
152f0 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
15300 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
15310 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15320 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
15330 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
15340 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
15350 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
15360 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
15370 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
15380 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
15390 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
153a0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
153b0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
153c0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
153d0 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
153e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
153f0 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
15400 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
15410 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
15420 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
15430 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
15440 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15450 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15470 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15480 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15490 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
154a0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
154b0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
154c0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
154d0 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
154e0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
154f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15500 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
15510 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
15520 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
15530 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
15540 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
15550 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
15560 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15570 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
15580 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
15590 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
155a0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
155b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
155c0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
155d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
155e0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
155f0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
15600 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
15610 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
15620 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15630 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
15640 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
15650 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
15660 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
15670 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
15680 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
15690 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
156a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
156b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
156c0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
156d0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
156e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
156f0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
15700 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
15710 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
15720 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
15730 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
15740 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
15750 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
15760 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15780 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15790 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
157a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
157b0 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
157c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
157d0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
157e0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
157f0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
15800 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15810 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
15820 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15830 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
15840 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
15850 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
15860 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
15870 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
15880 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
15890 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
158a0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
158b0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
158c0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
158d0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
158e0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
158f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15900 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
15910 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
15920 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15930 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
15940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15950 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15960 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15970 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
15980 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15990 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
159a0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
159b0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
159c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
159d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
159e0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
159f0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15a00 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
15a10 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
15a20 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
15a30 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
15a40 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
15a50 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
15a60 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
15a70 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
15a80 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
15a90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15aa0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15ab0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
15ac0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
15ad0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15ae0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
15af0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15b00 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15b10 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15b20 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15b30 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15b40 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15b50 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15b60 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15b70 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15b80 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15b90 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15ba0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15bb0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15bd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15be0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
15bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15c00 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
15c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
15c20 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
15c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15c40 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
15c50 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15c60 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
15c70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15c80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15c90 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15ca0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15cb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15cc0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15cd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15ce0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
15cf0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
15d00 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
15d10 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
15d20 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
15d30 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
15d40 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15d60 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15d70 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
15d80 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
15d90 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15da0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15db0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15dc0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15dd0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
15de0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
15df0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15e00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15e10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15e20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15e30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15e40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15e50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
15e60 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
15e70 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
15e80 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
15e90 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15ea0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15eb0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15ec0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15ed0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
15ee0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ef0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
15f00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
15f10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15f20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15f30 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
15f40 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15f50 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
15f60 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15f70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
15f80 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15f90 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
15fa0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
15fb0 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
15fc0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15fd0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
15fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
15ff0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16000 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16010 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16020 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16030 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
16040 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16050 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
16060 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
16070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16080 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
16090 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
160a0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
160b0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
160c0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
160d0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
160e0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
160f0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
16100 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
16110 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
16120 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16130 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16140 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
16150 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
16160 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16170 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16180 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
16190 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
161a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
161b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
161c0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
161d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
161e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
161f0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
16200 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16210 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16220 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
16230 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
16240 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
16250 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
16260 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16270 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
16280 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
16290 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
162a0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
162b0 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
162c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
162d0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
162e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
162f0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
16300 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
16310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16320 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
16330 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16340 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
16350 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16360 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16370 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16380 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
16390 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
163a0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
163b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
163c0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
163d0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
163e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
163f0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
16400 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
16410 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
16420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16430 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16440 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
16450 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
16460 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
16470 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
16480 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
16490 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
164a0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
164b0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
164c0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
164d0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
164e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
164f0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
16500 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
16510 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
16520 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16530 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
16540 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
16550 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
16560 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
16570 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
16580 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
16590 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
165a0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
165b0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
165c0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
165d0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
165e0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
165f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16600 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
16610 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
16620 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
16630 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16640 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
16650 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16660 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16670 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
16680 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
16690 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
166a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
166b0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
166c0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
166d0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
166e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
166f0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
16700 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
16710 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
16720 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
16730 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
16740 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16750 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
16760 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16770 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16780 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16790 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
167a0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
167b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
167c0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
167d0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
167e0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
167f0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
16800 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
16810 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
16820 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16830 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
16840 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
16850 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
16860 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
16870 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16880 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16890 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
168a0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
168b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
168c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
168d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
168e0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
168f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16900 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
16910 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16920 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
16930 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
16940 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
16950 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16960 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
16970 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
16980 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
16990 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
169a0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
169b0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
169c0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
169d0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
169e0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
169f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16a00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
16a10 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
16a20 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
16a30 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
16a40 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
16a50 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
16a60 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16a70 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
16a80 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
16a90 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
16aa0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
16ab0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16ac0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
16ad0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16ae0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
16af0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
16b00 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
16b10 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
16b20 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
16b30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
16b40 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
16b50 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
16b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16b70 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
16b80 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
16b90 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16ba0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
16bb0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
16bc0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
16bd0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
16be0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
16bf0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
16c00 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
16c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
16c20 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16c30 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
16c40 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16c50 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
16c60 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16c70 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16c80 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
16c90 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
16ca0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
16cb0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
16cc0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
16cd0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
16ce0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16cf0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
16d00 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
16d10 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
16d20 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
16d30 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
16d40 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16d50 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
16d60 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
16d70 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
16d80 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16d90 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16da0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
16db0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
16dc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16dd0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
16de0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
16df0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
16e00 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16e10 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
16e20 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
16e30 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
16e40 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
16e50 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
16e60 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
16e70 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
16e80 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
16e90 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
16ea0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
16eb0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
16ec0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
16ed0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
16ee0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
16ef0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
16f00 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
16f10 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
16f20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
16f30 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
16f40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16f50 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
16f60 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
16f70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16f80 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
16f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16fa0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
16fb0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
16fc0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
16fd0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
16fe0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
16ff0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
17000 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
17010 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
17020 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
17030 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
17040 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17050 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
17060 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17070 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
17080 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
17090 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
170a0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
170b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
170c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
170d0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
170e0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
170f0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
17100 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
17110 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
17120 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
17130 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
17140 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
17150 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
17160 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
17170 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
17180 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
17190 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
171a0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
171b0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
171c0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
171d0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
171e0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
171f0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
17200 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
17210 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17220 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
17230 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17240 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
17250 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17260 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
17270 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
17280 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17290 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
172a0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
172b0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
172c0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
172d0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
172e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
172f0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
17300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
17310 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
17320 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
17330 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
17340 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
17350 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
17360 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
17370 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
17380 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
17390 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
173a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
173b0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
173c0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
173d0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
173e0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
173f0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
17400 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
17410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17420 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
17430 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
17440 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
17450 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
17460 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
17470 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
17480 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17490 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
174a0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
174b0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
174c0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
174d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
174e0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
174f0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
17500 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
17510 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
17520 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
17530 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
17540 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
17550 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
17560 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
17570 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
17580 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
17590 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
175a0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
175b0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
175c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
175d0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
175e0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
175f0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
17600 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
17610 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17620 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
17630 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
17640 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
17650 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
17660 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
17670 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
17680 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
17690 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
176a0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
176b0 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
176c0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
176d0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
176e0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
176f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17700 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
17710 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
17720 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
17730 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17740 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
17750 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
17760 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17770 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17780 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17790 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
177a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
177b0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
177c0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
177d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
177e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
177f0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
17800 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
17810 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
17820 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
17830 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
17840 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
17850 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
17860 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
17870 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17880 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
17890 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
178a0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
178b0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
178c0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
178d0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
178e0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
178f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17900 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
17910 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17920 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
17930 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17940 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17950 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
17960 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17970 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17980 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17990 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
179a0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
179b0 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
179c0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
179d0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
179e0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
179f0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
17a00 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
17a10 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
17a20 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
17a30 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
17a40 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
17a50 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
17a60 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
17a70 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
17a80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17a90 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
17aa0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17ab0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
17ac0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17ad0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
17ae0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17af0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17b00 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
17b10 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
17b20 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
17b30 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
17b40 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
17b50 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
17b60 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
17b70 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
17b80 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
17b90 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17ba0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
17bb0 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
17bc0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
17bd0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
17be0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
17bf0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
17c00 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
17c10 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
17c20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
17c30 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
17c40 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
17c50 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
17c60 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
17c70 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
17c80 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
17c90 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
17ca0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
17cb0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
17cc0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
17cd0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
17ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17cf0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
17d00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17d10 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17d20 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
17d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17d40 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
17d50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17d60 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17d70 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
17d80 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
17d90 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
17da0 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
17db0 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
17dc0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
17dd0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
17de0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
17df0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
17e00 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
17e10 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
17e20 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
17e30 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
17e40 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
17e50 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
17e60 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
17e70 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
17e80 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
17e90 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
17ea0 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
17eb0 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
17ec0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
17ed0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
17ee0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
17ef0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
17f00 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
17f10 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
17f20 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
17f30 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
17f40 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
17f50 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
17f60 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
17f70 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
17f80 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
17f90 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
17fa0 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
17fb0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
17fc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17fd0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
17fe0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
17ff0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
18000 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  REF_SIZE.** <dd>
18010 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18020 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
18030 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20   option accepts 
18040 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
18050 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69  er.** of type (i
18060 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61  nt) - the new va
18070 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65  lue of the sorte
18080 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65  r-reference size
18090 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55   threshold..** U
180a0 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c  sually, when SQL
180b0 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65  ite uses an exte
180c0 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64  rnal sort to ord
180d0 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72  er records accor
180e0 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52  ding.** to an OR
180f0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61  DER BY clause, a
18100 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72  ll fields requir
18110 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
18120 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20   are present in 
18130 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65  the.** sorted re
18140 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20  cords. However, 
18150 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  if SQLite determ
18160 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68  ines based on th
18170 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a  e declared type.
18180 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f  ** of a table co
18190 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61  lumn that its va
181a0 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  lues are likely 
181b0 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65  to be very large
181c0 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61   - larger.** tha
181d0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64  n the configured
181e0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
181f0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
18200 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65   - then a refere
18210 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64  nce.** is stored
18220 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20   in each sorted 
18230 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72  record and the r
18240 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76  equired column v
18250 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20  alues loaded.** 
18260 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
18270 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65  e as records are
18280 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72   returned in sor
18290 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64  ted order. The d
182a0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
182b0 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
182c0 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20  is to never use 
182d0 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
182e0 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20  n. Specifying a 
182f0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c  .** negative val
18300 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69  ue for this opti
18310 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20  on restores the 
18320 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75  default behaviou
18330 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  r..** This optio
18340 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
18350 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
18360 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
18370 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
18380 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45  ABLE_SORTER_REFE
18390 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d  RENCES] compile-
183a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
183b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
183c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
183d0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
183e0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
183f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18400 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
18410 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
18420 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18430 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
18440 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
18450 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18460 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
18470 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
18480 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
18490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
184a0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
184b0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
184c0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
184d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
184e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
184f0 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e      6  /* No lon
18500 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
18510 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18520 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
18530 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
18540 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
18550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18560 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
18570 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
18580 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
18590 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
185a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
185b0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
185c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
185d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
185e0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
185f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18600 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
18610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18620 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
18630 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
18640 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
18650 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
18660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
18670 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
18680 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
18690 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
186a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
186b0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
186c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
186d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
186e0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
186f0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
18700 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18710 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
18720 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
18730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18740 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
18750 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
18760 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18770 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18780 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
18790 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
187a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
187b0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
187c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
187d0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
187e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
18800 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
18810 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18820 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
18840 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18850 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
18860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18870 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
18880 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
18890 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
188a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
188b0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
188c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
188d0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
188e0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
188f0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
18900 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
18910 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
18920 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18930 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18940 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
18950 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
18960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18970 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
18980 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
18990 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
189a0 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
189b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
189c0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
189d0 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
189e0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
189f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
18a00 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32  _MALLOC        2
18a10 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  7  /* boolean */
18a20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a30 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
18a40 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f  _SIZE      28  /
18a50 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
18a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18a70 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18a80 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18a90 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
18aa0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
18ab0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
18ac0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
18ad0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
18ae0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
18af0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
18b00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
18b10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
18b20 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
18b30 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
18b40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18b50 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
18b60 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
18b70 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
18b80 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
18b90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18ba0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
18bb0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
18bc0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
18bd0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
18be0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
18bf0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18c00 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
18c10 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
18c20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
18c30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18c40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
18c50 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
18c60 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
18c70 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
18c80 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
18c90 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
18ca0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
18cb0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
18cc0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18cd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18ce0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
18cf0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18d00 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18d10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18d20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18d30 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18d40 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18d50 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
18d60 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
18d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18d80 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
18d90 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
18da0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18db0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18dc0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
18dd0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
18de0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
18df0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18e00 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18e10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18e20 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18e30 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18e40 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18e50 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18e60 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18e70 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18e80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
18e90 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
18ea0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18eb0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
18ec0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
18ed0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
18ee0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18ef0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18f00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18f10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18f20 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18f30 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18f40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18f50 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18f60 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18f70 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18f80 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
18f90 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
18fa0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
18fb0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
18fc0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
18fd0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
18fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18ff0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
19000 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19010 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
19020 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
19030 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
19040 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
19050 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
19060 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
19070 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
19080 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
19090 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
190a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
190b0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
190c0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
190d0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
190e0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
190f0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
19100 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
19110 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
19120 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
19130 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
19140 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
19150 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
19160 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
19170 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
19180 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
19190 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
191a0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
191b0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
191c0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
191d0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
191e0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
191f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
19200 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
19210 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
19220 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
19230 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19240 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
19250 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
19260 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19270 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19280 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
19290 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
192a0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
192b0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
192c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
192d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
192e0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
192f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
19300 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
19310 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
19320 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
19330 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19340 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
19350 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
19360 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
19370 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
19380 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
19390 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
193a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
193b0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
193c0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
193d0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
193e0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
193f0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
19400 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
19410 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19420 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19430 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
19440 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
19450 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
19460 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19470 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19480 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19490 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
194a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
194b0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
194c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
194d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
194e0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
194f0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
19500 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
19510 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19520 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19530 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19540 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19550 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19560 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19570 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
19580 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
19590 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
195a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
195b0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
195c0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
195d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
195e0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
195f0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
19600 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
19610 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19620 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19630 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
19640 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
19650 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
19660 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
19670 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19680 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
19690 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
196a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
196b0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
196c0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
196d0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
196e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
196f0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
19700 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
19710 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19720 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19730 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19740 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
19750 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
19760 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
19770 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
19780 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
19790 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
197a0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
197b0 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
197c0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
197d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
197e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
197f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
19800 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
19810 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
19820 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
19830 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
19840 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19850 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
19860 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
19870 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19880 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
19890 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
198a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
198b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
198c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
198d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
198e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
198f0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
19900 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
19910 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
19920 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19930 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19940 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19950 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19960 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
19970 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
19980 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19990 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
199a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
199b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
199c0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
199d0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
199e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
199f0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19a00 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
19a10 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
19a20 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
19a30 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
19a40 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
19a50 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
19a60 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
19a70 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
19a80 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
19a90 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
19aa0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
19ab0 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
19ac0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
19ad0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
19ae0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
19af0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
19b00 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
19b10 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
19b20 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
19b30 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
19b40 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19b50 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
19b60 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
19b70 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
19b80 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
19b90 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
19ba0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
19bb0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
19bc0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
19bd0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
19be0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
19bf0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
19c00 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
19c10 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
19c20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19c30 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
19c40 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
19c50 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
19c60 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
19c70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19c80 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
19c90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ca0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19cb0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19cc0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19cd0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19ce0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
19cf0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19d00 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
19d10 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
19d20 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
19d30 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19d40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19d50 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
19d60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19d70 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19d80 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
19d90 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19da0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19db0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19dc0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
19dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19de0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19df0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19e00 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19e10 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19e20 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19e30 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19e40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19e50 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
19e60 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
19e70 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
19e80 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
19e90 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
19ea0 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
19eb0 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
19ec0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
19ed0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
19ee0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19ef0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19f00 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19f10 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19f20 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19f30 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19f40 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19f50 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
19f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19f70 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
19f80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19f90 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
19fa0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
19fb0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
19fc0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
19fd0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
19fe0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
19ff0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
1a000 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
1a010 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
1a020 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
1a030 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
1a040 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
1a050 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
1a060 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
1a070 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
1a080 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
1a090 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
1a0a0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
1a0b0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
1a0c0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
1a0d0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
1a0e0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
1a0f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a100 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a110 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
1a120 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
1a130 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
1a140 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
1a150 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
1a160 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
1a170 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
1a180 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
1a190 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1a1a0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
1a1b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1a1c0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1a1d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1a1e0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
1a1f0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1a200 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a210 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
1a220 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
1a230 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
1a240 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
1a250 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a260 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
1a270 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
1a280 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a290 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
1a2a0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
1a2b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a2c0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
1a2d0 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1a2e0 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1a2f0 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
1a300 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
1a310 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
1a320 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
1a330 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
1a340 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
1a350 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
1a360 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1a370 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
1a380 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
1a390 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
1a3a0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
1a3b0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
1a3c0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
1a3d0 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
1a3e0 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
1a3f0 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
1a400 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
1a410 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
1a420 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
1a430 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
1a440 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
1a450 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
1a460 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
1a470 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
1a480 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
1a490 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1a4a0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
1a4b0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
1a4c0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
1a4d0 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
1a4e0 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
1a4f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1a500 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
1a510 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
1a520 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
1a530 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
1a540 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1a550 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
1a560 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1a570 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1a580 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
1a590 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a5a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1a5b0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1a5c0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
1a5d0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1a5e0 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
1a5f0 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
1a600 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1a610 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1a620 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
1a630 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a640 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1a650 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1a660 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1a670 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1a680 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1a690 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1a6a0 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1a6b0 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1a6c0 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1a6d0 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1a6e0 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1a6f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1a700 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1a710 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1a720 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1a730 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1a740 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a750 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a760 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1a770 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1a780 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1a790 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1a7a0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1a7b0 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1a7c0 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1a7d0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1a7e0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1a7f0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1a800 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a810 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1a820 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1a830 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1a840 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1a850 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1a860 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1a870 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1a880 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1a890 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1a8a0 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1a8b0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
1a8c0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a8d0 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53  IG_RESET_DATABAS
1a8e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53  E</dt>.** <dd> S
1a8f0 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  et the SQLITE_DB
1a900 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1a910 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74  ABASE flag and t
1a920 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55  hen run.** [VACU
1a930 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  UM] in order to 
1a940 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73 65  reset a database
1a950 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74   back to an empt
1a960 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69  y database.** wi
1a970 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64  th no schema and
1a980 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65   no content. The
1a990 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65   following proce
1a9a0 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f  ss works even fo
1a9b0 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72  r.** a badly cor
1a9c0 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65 20  rupted database 
1a9d0 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  file:.** <ol>.**
1a9e0 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 64 61 74   <li> If the dat
1a9f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aa00 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64   is newly opened
1aa10 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 74 20 68  , make sure it h
1aa20 61 73 20 72 65 61 64 20 74 68 65 0a 2a 2a 20 20  as read the.**  
1aa30 20 20 20 20 64 61 74 61 62 61 73 65 20 73 63 68      database sch
1aa40 65 6d 61 20 62 79 20 70 72 65 70 61 72 69 6e 67  ema by preparing
1aa50 20 74 68 65 6e 20 64 69 73 63 61 72 64 69 6e 67   then discarding
1aa60 20 73 6f 6d 65 20 71 75 65 72 79 20 61 67 61 69   some query agai
1aa70 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  nst the.**      
1aa80 64 61 74 61 62 61 73 65 2c 20 6f 72 20 63 61 6c  database, or cal
1aa90 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 74 61 62  ling sqlite3_tab
1aaa0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
1aab0 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61  ta(), ignoring a
1aac0 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 72 6f 72  ny.**      error
1aad0 73 2e 20 20 54 68 69 73 20 73 74 65 70 20 69 73  s.  This step is
1aae0 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 72 79 20   only necessary 
1aaf0 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  if the applicati
1ab00 6f 6e 20 64 65 73 69 72 65 73 20 74 6f 20 6b 65  on desires to ke
1ab10 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 64  ep.**      the d
1ab20 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1ab30 6f 64 65 20 61 66 74 65 72 20 74 68 65 20 72 65  ode after the re
1ab40 73 65 74 20 69 66 20 69 74 20 77 61 73 20 69 6e  set if it was in
1ab50 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65   WAL mode before
1ab60 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 72 65 73  .**      the res
1ab70 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71  et.  .** <li> sq
1ab80 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
1ab90 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  db, SQLITE_DBCON
1aba0 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1abb0 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c  SE, 1, 0);.** <l
1abc0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  i> [sqlite3_exec
1abd0 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22  ](db, "[VACUUM]"
1abe0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c  , 0, 0, 0);.** <
1abf0 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1ac00 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1ac10 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1ac20 44 41 54 41 42 41 53 45 2c 20 30 2c 20 30 29 3b  DATABASE, 0, 0);
1ac30 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63  .** </ol>.** Bec
1ac40 61 75 73 65 20 72 65 73 65 74 74 69 6e 67 20 61  ause resetting a
1ac50 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 73   database is des
1ac60 74 72 75 63 74 69 76 65 20 61 6e 64 20 69 72 72  tructive and irr
1ac70 65 76 65 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a  eversible, the.*
1ac80 2a 20 70 72 6f 63 65 73 73 20 72 65 71 75 69 72  * process requir
1ac90 65 73 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  es the use of th
1aca0 69 73 20 6f 62 73 63 75 72 65 20 41 50 49 20 61  is obscure API a
1acb0 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 74 65 70  nd multiple step
1acc0 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73  s to help.** ens
1acd0 75 72 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  ure that it does
1ace0 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 79 20 61   not happen by a
1acf0 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 3c  ccident..**.** <
1ad00 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1ad10 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 74  IG_DEFENSIVE</dt
1ad20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1ad30 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1ad40 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 63  ENSIVE option ac
1ad50 74 69 76 65 73 20 6f 72 20 64 65 61 63 74 69 76  tives or deactiv
1ad60 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 64 65 66  ates the.** "def
1ad70 65 6e 73 69 76 65 22 20 66 6c 61 67 20 66 6f 72  ensive" flag for
1ad80 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1ad90 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20 74 68  ection.  When th
1ada0 65 20 64 65 66 65 6e 73 69 76 65 0a 2a 2a 20 66  e defensive.** f
1adb0 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  lag is enabled, 
1adc0 73 6f 6d 65 20 6f 62 73 63 75 72 65 20 66 65 61  some obscure fea
1add0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 20  tures of SQLite 
1ade0 61 72 65 20 64 69 73 61 62 6c 65 64 20 69 6e 20  are disabled in 
1adf0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 72 65 64 75  order.** to redu
1ae00 63 65 20 74 68 65 20 61 74 74 61 63 6b 20 73 75  ce the attack su
1ae10 72 66 61 63 65 2e 20 41 70 70 6c 69 63 61 74 69  rface. Applicati
1ae20 6f 6e 73 20 74 68 61 74 20 72 75 6e 20 75 6e 74  ons that run unt
1ae30 72 75 73 74 65 64 20 53 51 4c 0a 2a 2a 20 63 61  rusted SQL.** ca
1ae40 6e 20 61 63 74 69 76 61 74 65 20 74 68 69 73 20  n activate this 
1ae50 66 6c 61 67 20 74 6f 20 72 65 64 75 63 65 20 74  flag to reduce t
1ae60 68 65 20 72 69 73 6b 20 6f 66 20 7a 65 72 6f 2d  he risk of zero-
1ae70 64 61 79 20 65 78 70 6c 6f 69 74 73 2e 0a 2a 2a  day exploits..**
1ae80 20 3c 70 3e 0a 2a 2a 20 46 65 61 74 75 72 65 73   <p>.** Features
1ae90 20 64 69 73 61 62 6c 65 64 20 62 79 20 74 68 65   disabled by the
1aea0 20 64 65 66 65 6e 73 69 76 65 20 66 6c 61 67 20   defensive flag 
1aeb0 69 6e 63 6c 75 64 65 3a 0a 2a 2a 20 3c 75 6c 3e  include:.** <ul>
1aec0 0a 2a 2a 20 3c 6c 69 3e 54 68 65 20 5b 50 52 41  .** <li>The [PRA
1aed0 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
1aee0 65 6d 61 3d 4f 4e 5d 20 73 74 61 74 65 6d 65 6e  ema=ON] statemen
1aef0 74 2e 0a 2a 2a 20 3c 6c 69 3e 57 72 69 74 65 73  t..** <li>Writes
1af00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 5f   to the [sqlite_
1af10 64 62 70 61 67 65 5d 20 76 69 72 74 75 61 6c 20  dbpage] virtual 
1af20 74 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  table..** </ul>.
1af30 2a 2a 20 4e 65 77 20 72 65 73 74 72 69 63 74 69  ** New restricti
1af40 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
1af50 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1af60 73 65 73 2e 0a 2a 2a 20 3c 70 3e 0a 2a 2a 20 54  ses..** <p>.** T
1af70 6f 20 62 65 20 63 6c 65 61 72 3a 20 49 74 20 73  o be clear: It s
1af80 68 6f 75 6c 64 20 6e 65 76 65 72 20 62 65 20 70  hould never be p
1af90 6f 73 73 69 62 6c 65 20 66 6f 72 20 68 6f 73 74  ossible for host
1afa0 69 6c 65 20 53 51 4c 20 74 6f 20 63 61 75 73 65  ile SQL to cause
1afb0 0a 2a 2a 20 61 72 62 69 74 72 61 72 79 20 6d 65  .** arbitrary me
1afc0 6d 6f 72 79 20 72 65 61 64 73 2c 20 6d 65 6d 6f  mory reads, memo
1afd0 72 79 20 6c 65 61 6b 73 2c 20 62 75 66 66 65 72  ry leaks, buffer
1afe0 20 6f 76 65 72 66 6c 6f 77 73 2c 20 61 73 73 65   overflows, asse
1aff0 72 74 69 6f 6e 0a 2a 2a 20 66 61 75 6c 74 73 2c  rtion.** faults,
1b000 20 61 72 62 69 74 72 61 72 79 20 63 6f 64 65 20   arbitrary code 
1b010 65 78 65 63 75 74 69 6f 6e 2c 20 63 72 61 73 68  execution, crash
1b020 65 73 2c 20 6f 72 20 6f 74 68 65 72 20 6d 69 73  es, or other mis
1b030 63 68 69 65 66 2c 20 72 65 67 61 72 64 6c 65 73  chief, regardles
1b040 73 0a 2a 2a 20 6f 66 20 74 68 65 20 76 61 6c 75  s.** of the valu
1b050 65 20 6f 66 20 74 68 65 20 64 65 66 65 6e 73 69  e of the defensi
1b060 76 65 20 66 6c 61 67 2e 20 20 41 6e 79 20 6f 63  ve flag.  Any oc
1b070 63 75 72 72 61 6e 63 65 20 6f 66 20 74 68 65 73  currance of thes
1b080 65 20 70 72 6f 62 6c 65 6d 73 0a 2a 2a 20 69 73  e problems.** is
1b090 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 73 65   considered a se
1b0a0 72 69 6f 75 73 20 62 75 67 20 61 6e 64 20 77 69  rious bug and wi
1b0b0 6c 6c 20 62 65 20 66 69 78 65 64 20 70 72 6f 6d  ll be fixed prom
1b0c0 70 74 6c 79 2e 20 20 49 74 20 69 73 20 6e 6f 74  ptly.  It is not
1b0d0 0a 2a 2a 20 6e 65 63 65 73 73 61 72 79 20 74 6f  .** necessary to
1b0e0 20 65 6e 61 62 6c 65 20 74 68 65 20 64 65 66 65   enable the defe
1b0f0 6e 73 69 76 65 20 66 6c 61 67 20 69 6e 20 6f 72  nsive flag in or
1b100 64 65 72 20 74 6f 20 6d 61 6b 65 20 53 51 4c 69  der to make SQLi
1b110 74 65 20 73 65 63 75 72 65 0a 2a 2a 20 61 67 61  te secure.** aga
1b120 69 6e 73 74 20 61 74 74 61 63 6b 2e 20 54 68 65  inst attack. The
1b130 20 64 65 66 65 6e 73 69 76 65 20 66 6c 61 67 20   defensive flag 
1b140 6d 65 72 65 6c 79 20 70 72 6f 76 69 64 65 73 20  merely provides 
1b150 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 6c 61  an additional la
1b160 79 65 72 0a 2a 2a 20 6f 66 20 64 65 66 65 6e 73  yer.** of defens
1b170 65 20 61 67 61 69 6e 73 74 20 75 6e 6b 6e 6f 77  e against unknow
1b180 6e 20 76 75 6c 6e 65 72 61 62 69 6c 69 74 69 65  n vulnerabilitie
1b190 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c  s..** </dd>.** <
1b1a0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1b1b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b1c0 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
1b1d0 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
1b1e0 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
1b1f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b200 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
1b210 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
1b220 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
1b230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b240 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1b250 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
1b260 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
1b270 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b280 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1b290 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
1b2a0 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
1b2b0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b2c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b2d0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
1b2e0 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
1b2f0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b300 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b310 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
1b320 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
1b330 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b340 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b350 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
1b360 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
1b370 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b390 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1b3a0 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37  G           1007
1b3b0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b3d0 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1b3e0 45 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30  EQP           10
1b3f0 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  08 /* int int* *
1b400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b410 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1b420 44 41 54 41 42 41 53 45 20 20 20 20 20 20 20 20  DATABASE        
1b430 31 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1009 /* int int*
1b440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b450 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45  TE_DBCONFIG_DEFE
1b460 4e 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  NSIVE           
1b470 20 20 31 30 31 30 20 2f 2a 20 69 6e 74 20 69 6e    1010 /* int in
1b480 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b490 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1b4a0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  X               
1b4b0 20 20 20 20 31 30 31 30 20 2f 2a 20 4c 61 72 67      1010 /* Larg
1b4c0 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a  est DBCONFIG */.
1b4d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b4e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1b4f0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1b500 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
1b510 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b520 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1b530 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1b540 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
1b550 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1b560 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
1b570 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1b580 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
1b590 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
1b5a0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
1b5b0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
1b5c0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
1b5d0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
1b5e0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
1b5f0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1b600 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
1b610 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
1b620 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1b630 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
1b640 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
1b650 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b660 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
1b670 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
1b680 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
1b690 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1b6a0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
1b6b0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
1b6c0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
1b6d0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
1b6e0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
1b6f0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
1b700 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
1b710 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
1b720 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
1b730 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
1b740 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
1b750 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
1b760 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
1b770 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
1b780 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
1b790 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
1b7a0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
1b7b0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
1b7c0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
1b7d0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
1b7e0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
1b7f0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
1b800 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
1b810 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1b820 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
1b830 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
1b840 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
1b850 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
1b860 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
1b870 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
1b880 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
1b890 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
1b8a0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
1b8b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
1b8c0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
1b8d0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1b8e0 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
1b8f0 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
1b900 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1b910 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
1b920 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
1b930 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
1b940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b950 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
1b960 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1b970 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
1b980 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
1b990 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
1b9a0 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
1b9b0 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
1b9c0 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
1b9d0 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
1b9e0 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
1b9f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1ba00 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
1ba10 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
1ba20 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1ba30 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1ba40 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
1ba50 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
1ba60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1ba70 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
1ba80 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1ba90 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
1baa0 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
1bab0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
1bac0 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
1bad0 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
1bae0 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
1baf0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
1bb00 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bb10 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
1bb20 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
1bb30 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
1bb40 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
1bb50 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
1bb60 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
1bb70 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
1bb80 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
1bb90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1bba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
1bbb0 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
1bbc0 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
1bbd0 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
1bbe0 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
1bbf0 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
1bc00 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
1bc10 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
1bc20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1bc30 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bc40 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1bc50 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1bc60 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1bc70 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1bc80 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1bc90 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1bca0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1bcb0 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1bcc0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1bcd0 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1bce0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1bcf0 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1bd00 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1bd10 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1bd20 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1bd30 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1bd40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1bd50 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1bd60 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1bd70 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1bd80 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1bd90 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1bda0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1bdb0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1bdc0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1bdd0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1bde0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1bdf0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1be00 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1be10 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1be20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1be30 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1be40 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1be50 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1be60 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1be70 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1be80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1be90 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1bea0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1beb0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1bec0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1bed0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1bee0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1bef0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1bf00 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1bf10 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1bf20 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1bf30 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1bf40 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1bf50 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1bf60 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1bf70 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1bf80 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1bf90 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1bfa0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1bfb0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1bfc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1bfd0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1bfe0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1bff0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1c000 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1c010 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1c020 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1c030 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1c040 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1c050 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1c060 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1c070 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1c080 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1c090 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1c0a0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1c0b0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1c0c0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1c0d0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1c0e0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1c0f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1c100 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1c110 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c120 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1c130 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1c140 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1c150 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1c160 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1c170 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c180 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1c190 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1c1a0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1c1b0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1c1c0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1c1d0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1c1e0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1c1f0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1c200 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c210 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c220 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1c230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c240 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1c250 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1c260 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1c270 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1c280 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1c290 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1c2a0 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1c2b0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1c2c0 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1c2d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c2e0 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1c2f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c300 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1c310 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1c320 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1c330 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1c340 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1c350 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c360 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1c370 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1c380 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1c390 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1c3a0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1c3b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c3c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c3d0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1c3e0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1c3f0 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1c400 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1c410 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1c420 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1c430 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c440 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1c450 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1c460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c470 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1c480 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1c490 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1c4a0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1c4b0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1c4c0 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1c4d0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1c4e0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1c4f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1c500 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1c510 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1c520 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1c530 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1c540 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1c550 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1c560 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1c570 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1c580 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1c590 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1c5a0 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1c5b0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1c5c0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1c5d0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1c5e0 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1c5f0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1c600 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1c610 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1c620 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1c630 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1c640 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1c650 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1c660 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1c670 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1c680 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1c690 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1c6a0 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1c6b0 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1c6c0 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1c6d0 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1c6e0 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1c6f0 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1c700 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1c710 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1c720 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1c730 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1c740 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1c750 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1c760 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1c770 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1c780 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1c790 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1c7a0 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1c7b0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1c7c0 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1c7d0 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1c7e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1c7f0 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1c800 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1c810 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1c820 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1c830 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1c840 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1c850 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1c860 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1c870 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1c880 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1c890 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1c8a0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1c8b0 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1c8c0 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1c8d0 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1c8e0 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1c8f0 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1c900 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1c910 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1c920 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1c930 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1c940 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1c950 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1c960 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1c970 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1c980 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1c990 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1c9a0 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1c9b0 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1c9c0 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1c9d0 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1c9e0 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1c9f0 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1ca00 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ca10 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1ca20 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1ca30 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1ca40 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1ca50 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1ca60 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1ca70 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1ca80 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1ca90 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1caa0 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1cab0 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1cac0 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1cad0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1cae0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1caf0 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1cb00 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1cb10 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1cb20 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1cb30 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1cb40 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1cb50 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1cb60 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1cb70 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1cb80 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1cb90 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1cba0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1cbb0 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1cbc0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1cbd0 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1cbe0 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1cbf0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1cc00 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1cc10 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1cc20 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  rigger..**.** If
1cc30 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1cc40 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1cc50 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1cc60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cc70 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1cc80 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1cc90 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1cca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ccb0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1ccc0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1ccd0 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ningful..**.** S
1cce0 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e  ee also:.** <ul>
1ccf0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71  .** <li> the [sq
1cd00 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1cd10 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1cd20 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1cd30 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1cd40 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1cd50 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1cd60 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1cd70 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1cd80 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f  on pragma].** </
1cd90 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul>.*/.int sqlit
1cda0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1cdb0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1cdc0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1cdd0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1cde0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1cdf0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1ce00 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1ce10 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1ce20 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1ce30 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1ce40 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1ce50 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1ce60 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1ce70 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1ce80 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1ce90 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1cea0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1ceb0 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1cec0 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1ced0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1cee0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1cef0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1cf00 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1cf10 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1cf20 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1cf30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1cf40 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1cf50 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1cf60 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1cf70 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1cf80 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1cf90 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1cfa0 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1cfb0 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1cfc0 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1cfd0 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1cfe0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1cff0 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1d000 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1d010 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1d020 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1d030 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1d040 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1d050 68 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  his the [sqlite3
1d060 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 44  _total_changes(D
1d070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  )] interface onl
1d080 79 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75  y reports the nu
1d090 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20  mber.** of rows 
1d0a0 74 68 61 74 20 63 68 61 6e 67 65 64 20 64 75 65  that changed due
1d0b0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1d0c0 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20 64 61  t run against da
1d0d0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
1d0e0 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68 61  tion D.  Any cha
1d0f0 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20 64 61  nges by other da
1d100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d110 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  ns are ignored..
1d120 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63 68 61  ** To detect cha
1d130 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61 20 64  nges against a d
1d140 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 72 6f  atabase file fro
1d150 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  m other database
1d160 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1d170 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d 41 20  use the [PRAGMA 
1d180 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f  data_version] co
1d190 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20  mmand or the.** 
1d1a0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
1d1b0 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c  TA_VERSION] [fil
1d1c0 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a  e control]..** .
1d1d0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1d1e0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1d1f0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1d200 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d210 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1d220 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1d230 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1d240 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1d250 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1d260 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1d270 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1d280 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ul..**.** See al
1d290 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  so:.** <ul>.** <
1d2a0 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  li> the [sqlite3
1d2b0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1d2c0 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68  rface.** <li> th
1d2d0 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  e [count_changes
1d2e0 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e   pragma].** <li>
1d2f0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1d300 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a  SQL function].**
1d310 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 5f   <li> the [data_
1d320 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a  version pragma].
1d330 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c  ** <li> the [SQL
1d340 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
1d350 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f  ERSION] [file co
1d360 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ntrol].** </ul>.
1d370 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1d380 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1d390 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d3a0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1d3b0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1d3c0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1d3d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1d3e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1d3f0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1d400 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1d410 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1d420 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1d430 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1d440 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1d450 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1d460 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1d470 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1d480 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1d490 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1d4a0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1d4b0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1d4c0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1d4d0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1d4e0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1d4f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1d500 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1d510 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1d520 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1d530 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1d540 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1d550 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1d560 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1d570 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1d580 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1d590 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1d5a0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1d5b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d5c0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1d5d0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1d5e0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1d5f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1d600 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1d610 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1d620 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1d630 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1d640 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1d650 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d660 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1d670 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1d680 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1d690 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1d6a0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1d6b0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1d6c0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1d6d0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1d6e0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1d6f0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1d700 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1d710 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1d720 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1d730 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1d740 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1d750 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1d760 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1d770 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1d780 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1d790 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1d7a0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1d7b0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1d7c0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1d7d0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1d7e0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1d7f0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1d800 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1d810 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1d820 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1d830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d840 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1d850 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1d860 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1d870 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1d880 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1d890 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1d8a0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1d8b0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1d8c0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1d8d0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1d8e0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1d8f0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1d900 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1d910 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1d920 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1d930 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1d940 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1d950 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1d960 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1d970 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1d980 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1d990 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1d9a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1d9b0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1d9c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1d9d0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1d9e0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1d9f0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1da00 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1da10 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1da20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1da30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1da40 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1da50 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1da60 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1da70 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64  returns..*/.void
1da80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1da90 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1daa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1dab0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1dac0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1dad0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1dae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1daf0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1db00 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1db10 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1db20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1db30 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1db40 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1db50 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1db60 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1db70 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1db80 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1db90 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1dba0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1dbb0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1dbc0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1dbd0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1dbe0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1dbf0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1dc00 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1dc10 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1dc20 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1dc30 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1dc40 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1dc50 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1dc60 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1dc70 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1dc80 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1dc90 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1dca0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1dcb0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1dcc0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1dcd0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1dce0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1dcf0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1dd00 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1dd10 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1dd20 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1dd30 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1dd40 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1dd50 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1dd60 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1dd70 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1dd80 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1dd90 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1dda0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1ddb0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1ddc0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1ddd0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1dde0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1ddf0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1de00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1de10 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1de20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1de30 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1de40 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1de50 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1de60 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1de70 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1de80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1de90 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1dea0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1deb0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1dec0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1ded0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1dee0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1def0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1df00 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1df10 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1df20 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1df30 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1df40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1df50 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1df60 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1df70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1df80 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1df90 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1dfa0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1dfb0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1dfc0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1dfd0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1dfe0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1dff0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1e000 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1e010 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1e020 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1e030 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1e040 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1e050 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1e060 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1e070 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1e080 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1e090 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e0a0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1e0b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1e0c0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1e0d0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1e0e0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1e0f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1e100 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1e110 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1e120 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1e130 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1e140 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1e150 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1e160 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1e170 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1e180 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1e190 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1e1a0 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1e1b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1e1c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1e1d0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e1e0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1e1f0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1e200 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1e210 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1e220 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1e230 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1e240 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1e250 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1e260 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1e270 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1e280 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e290 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1e2a0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1e2b0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1e2c0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1e2d0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1e2e0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1e2f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1e300 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1e310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1e320 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1e330 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1e340 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1e350 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1e360 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1e370 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1e380 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1e390 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1e3a0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1e3b0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1e3c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1e3d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1e3e0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1e3f0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1e400 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1e410 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1e420 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1e430 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1e440 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1e450 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1e460 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1e470 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1e480 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1e490 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1e4a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1e4b0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1e4c0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1e4d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1e4e0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1e4f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1e500 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1e510 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1e520 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1e530 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1e540 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1e550 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1e560 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1e570 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1e580 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1e590 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1e5a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1e5b0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1e5c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e5d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1e5e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1e5f0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1e600 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1e610 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1e620 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1e630 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1e640 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1e650 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1e660 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1e670 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1e680 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1e690 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1e6a0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1e6b0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1e6c0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1e6d0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1e6e0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1e6f0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1e700 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1e710 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1e720 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1e730 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1e740 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1e750 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1e760 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1e770 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1e780 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1e790 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1e7a0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1e7b0 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1e7c0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1e7d0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1e7e0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1e7f0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1e800 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1e810 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1e820 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1e830 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1e840 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1e850 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1e860 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1e870 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1e880 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1e890 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1e8a0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1e8b0 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1e8c0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1e8d0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1e8e0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1e8f0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1e900 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1e910 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1e920 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1e930 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1e940 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1e950 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1e960 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1e970 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1e980 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1e990 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1e9a0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1e9b0 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1e9c0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1e9d0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1e9e0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1e9f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1ea00 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1ea10 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1ea20 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ea30 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1ea40 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1ea50 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1ea60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ea70 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1ea80 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1ea90 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1eaa0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1eab0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1eac0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1ead0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1eae0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1eaf0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1eb00 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1eb10 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1eb20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1eb30 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1eb40 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1eb50 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1eb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1eb70 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1eb80 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1eb90 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1eba0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1ebb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1ebc0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1ebd0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1ebe0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1ebf0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ec00 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1ec10 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1ec20 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1ec30 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1ec40 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1ec50 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1ec60 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1ec70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ec80 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1ec90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1eca0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1ecb0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1ecc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1ecd0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1ece0 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1ecf0 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1ed00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1ed10 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1ed20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1ed30 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1ed40 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1ed50 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1ed60 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1ed70 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1ed80 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1ed90 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1eda0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1edb0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1edc0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1edd0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1ede0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1edf0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1ee00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1ee10 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1ee20 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1ee30 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1ee40 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1ee50 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1ee60 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1ee70 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1ee80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1ee90 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1eea0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1eeb0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1eec0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1eed0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1eee0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1eef0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1ef00 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1ef10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1ef20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1ef30 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1ef40 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1ef50 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ef60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1ef70 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1ef80 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1ef90 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1efa0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1efb0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1efc0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1efd0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1efe0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1eff0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1f000 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1f010 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1f020 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1f030 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1f040 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1f050 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1f060 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1f070 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1f080 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1f090 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1f0a0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1f0b0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1f0c0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1f0d0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1f0e0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1f0f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f100 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1f110 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1f120 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1f130 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1f140 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1f150 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1f160 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1f170 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1f180 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1f190 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1f1a0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1f1b0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1f1c0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1f1d0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1f1e0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1f1f0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1f200 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1f210 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1f220 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1f230 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1f240 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1f250 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1f260 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1f270 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1f280 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1f290 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1f2a0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1f2b0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1f2c0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1f2d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1f2e0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1f2f0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1f300 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1f310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f320 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1f330 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1f340 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1f350 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1f360 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1f370 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1f380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1f390 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1f3a0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1f3b0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1f3c0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1f3d0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1f3e0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1f3f0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1f400 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1f410 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1f420 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1f430 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1f440 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1f450 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1f460 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1f470 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f480 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1f490 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1f4a0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1f4b0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1f4c0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1f4d0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1f4e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1f4f0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1f500 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1f510 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1f520 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1f530 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1f540 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1f550 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1f560 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1f570 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1f580 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1f590 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1f5a0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1f5b0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1f5c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f5d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1f5e0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1f5f0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1f600 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f610 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1f620 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1f630 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1f640 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1f650 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1f660 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1f670 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1f680 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1f690 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1f6a0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1f6b0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1f6c0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1f6d0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1f6e0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1f6f0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1f700 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1f710 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1f720 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1f730 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1f740 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1f750 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f760 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f770 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1f780 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1f790 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1f7a0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1f7b0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1f7c0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1f7d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1f7e0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1f7f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f800 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1f810 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f820 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1f830 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1f840 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1f850 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1f860 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1f870 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1f880 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1f890 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f8a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1f8b0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1f8c0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1f8d0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1f8e0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1f8f0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1f900 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1f910 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1f920 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1f930 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1f940 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1f950 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1f960 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1f970 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1f980 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1f990 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1f9a0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1f9b0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1f9c0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1f9d0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1f9e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1f9f0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1fa00 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1fa10 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1fa20 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1fa30 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1fa40 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1fa50 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1fa60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1fa70 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1fa80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1fa90 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1faa0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1fab0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1fac0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1fad0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1fae0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1faf0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1fb00 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1fb10 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1fb20 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1fb30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1fb40 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1fb50 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1fb60 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1fb70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1fb80 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1fb90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1fba0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1fbb0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1fbc0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1fbd0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1fbe0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1fbf0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1fc00 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1fc10 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1fc20 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1fc30 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1fc40 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1fc50 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1fc60 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1fc70 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1fc80 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1fc90 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1fca0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1fcb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1fcc0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1fcd0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1fce0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1fcf0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1fd00 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1fd10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1fd20 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1fd30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1fd40 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1fd50 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1fd60 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1fd70 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1fd80 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1fd90 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1fda0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1fdb0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1fdc0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1fdd0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1fde0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1fdf0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1fe00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1fe10 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1fe20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1fe30 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1fe40 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1fe50 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1fe60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1fe70 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1fe80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fe90 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1fea0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1feb0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1fec0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1fed0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1fee0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1fef0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1ff00 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1ff10 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1ff20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ff30 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1ff40 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66   of the common f
1ff50 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ff60 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  s from.** the st
1ff70 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70  andard library p
1ff80 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73  rintf() .** plus
1ff90 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ffa0 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1ffb0 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51  rmats ([%q], [%Q
1ffc0 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a  ], [%w], and [%z
1ffd0 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  ])..** See the [
1ffe0 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28  built-in printf(
1fff0 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
20000 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a   for details..**
20010 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20020 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
20030 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
20040 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
20050 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
20060 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
20070 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
20080 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
20090 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
200a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
200b0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
200c0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
200d0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
200e0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
200f0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
20100 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
20110 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
20120 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75  malloc64()] is u
20130 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
20140 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
20150 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
20160 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
20170 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
20180 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
20190 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
201a0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
201b0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
201c0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
201d0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
201e0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
201f0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
20200 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
20210 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
20220 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
20230 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
20240 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
20250 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
20260 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
20270 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
20280 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
20290 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
202a0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
202b0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
202c0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
202d0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
202e0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
202f0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
20300 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
20310 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
20320 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
20330 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
20340 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
20350 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
20360 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
20370 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
20380 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
20390 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
203a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
203b0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
203c0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
203d0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
203e0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
203f0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
20400 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
20410 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
20420 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
20430 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
20440 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
20450 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
20460 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
20470 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
20480 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
20490 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
204a0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
204b0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
204c0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
204d0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
204e0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
204f0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
20500 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
20510 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
20520 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
20530 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
20540 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
20550 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
20560 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
20570 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
20580 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
20590 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
205a0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
205b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
205c0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
205d0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
205e0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  intf()..**.** Se
205f0 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d  e also:  [built-
20600 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70  in printf()], [p
20610 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63  rintf() SQL func
20620 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion].*/.char *s
20630 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
20640 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
20650 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
20660 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
20670 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
20680 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
20690 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
206a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
206b0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
206c0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
206d0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
206e0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
206f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
20700 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
20710 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
20720 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
20730 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
20740 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
20750 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
20760 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
20770 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
20780 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
20790 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
207a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
207b0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
207c0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
207d0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
207e0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
207f0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
20800 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
20810 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
20820 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
20830 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
20840 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
20850 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
20860 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
20870 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
20880 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
20890 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
208a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
208b0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
208c0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
208d0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
208e0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
208f0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
20900 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20910 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
20920 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
20930 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
20940 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
20950 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
20960 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
20970 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
20980 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
20990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
209a0 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
209b0 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
209c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
209d0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
209e0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
209f0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
20a00 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
20a10 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
20a20 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
20a30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
20a40 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
20a50 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
20a60 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
20a70 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
20a80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
20a90 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
20aa0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
20ab0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
20ac0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
20ad0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
20ae0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
20af0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
20b00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
20b10 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
20b20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
20b30 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
20b40 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
20b50 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
20b60 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
20b70 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
20b80 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
20b90 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
20ba0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
20bb0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
20bc0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
20bd0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
20be0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
20bf0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
20c00 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
20c10 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
20c20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
20c30 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
20c40 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
20c50 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
20c60 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
20c70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
20c80 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
20c90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
20ca0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
20cb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
20cc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
20cd0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
20ce0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
20cf0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
20d00 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
20d10 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
20d20 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
20d30 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
20d40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20d50 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
20d60 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
20d70 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
20d80 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
20d90 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
20da0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20db0 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
20dc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20dd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
20de0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
20df0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
20e00 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
20e10 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
20e20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
20e30 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
20e40 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
20e50 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
20e60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
20e70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20e80 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
20e90 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
20ea0 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
20eb0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
20ec0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
20ed0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
20ee0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
20ef0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
20f00 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
20f10 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
20f20 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
20f30 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
20f40 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
20f50 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
20f60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20f70 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
20f80 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
20f90 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
20fa0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20fb0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
20fc0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
20fd0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
20fe0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
20ff0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
21000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21010 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
21020 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
21030 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
21040 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
21050 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
21060 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
21070 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
21080 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
21090 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
210a0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
210b0 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
210c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
210d0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
210e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
210f0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
21100 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
21110 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
21120 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
21130 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
21140 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
21150 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
21160 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
21170 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
21180 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
21190 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
211a0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
211b0 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
211c0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
211d0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
211e0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
211f0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
21200 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
21210 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
21220 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
21230 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
21240 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
21250 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
21260 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
21270 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
21280 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
21290 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
212a0 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
212b0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
212c0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
212d0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
212e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
212f0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
21300 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
21310 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
21320 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
21330 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
21340 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
21350 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
21360 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
21370 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
21380 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
21390 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
213a0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
213b0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
213c0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
213d0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
213e0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
213f0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
21400 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
21410 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
21420 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
21430 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
21440 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
21450 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
21460 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
21470 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
21480 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
21490 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
214a0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
214b0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
214c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
214d0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
214e0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
214f0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
21500 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
21510 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
21520 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
21530 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
21540 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
21550 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
21560 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
21570 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
21580 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
21590 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
215a0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
215b0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
215c0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
215d0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
215e0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
215f0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
21600 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
21610 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
21620 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
21630 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
21640 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
21650 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
21660 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
21670 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
21680 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
21690 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
216a0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
216b0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
216c0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
216d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
216e0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
216f0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
21700 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
21710 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
21720 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
21730 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
21740 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
21750 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
21760 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
21770 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
21780 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
21790 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
217a0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
217b0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
217c0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
217d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
217e0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
217f0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
21800 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
21810 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
21820 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
21830 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
21840 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
21850 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
21860 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
21870 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
21880 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
21890 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
218a0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
218b0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
218c0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
218d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
218e0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
218f0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
21900 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
21910 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
21920 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
21930 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
21940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
21950 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
21960 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
21970 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
21980 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
21990 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
219a0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
219b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
219c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
219d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
219e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
219f0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
21a00 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
21a10 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
21a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21a30 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
21a40 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
21a50 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
21a60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21a70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
21a80 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
21a90 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
21aa0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
21ab0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
21ac0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
21ad0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
21ae0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
21af0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
21b00 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
21b10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
21b20 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
21b30 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
21b40 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
21b50 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
21b60 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
21b70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
21b80 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
21b90 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21ba0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
21bb0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
21bc0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
21bd0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
21be0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
21bf0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
21c00 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
21c10 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
21c20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
21c30 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
21c40 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
21c50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
21c60 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
21c70 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
21c80 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
21c90 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
21ca0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
21cb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
21cc0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
21cd0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
21ce0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
21cf0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21d00 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
21d10 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
21d20 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
21d30 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
21d40 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
21d50 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
21d60 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
21d70 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
21d80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
21d90 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
21da0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
21db0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
21dc0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
21dd0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
21de0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
21df0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
21e00 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
21e10 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
21e20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
21e30 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
21e40 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
21e50 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
21e60 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
21e70 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
21e80 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
21e90 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
21ea0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
21eb0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
21ec0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
21ed0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
21ee0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
21ef0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
21f00 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
21f10 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
21f20 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
21f30 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
21f40 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
21f50 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
21f60 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
21f70 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
21f80 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
21f90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
21fa0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
21fb0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
21fc0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
21fd0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
21fe0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
21ff0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
22000 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
22010 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
22020 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
22030 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
22040 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
22050 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
22060 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
22070 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
22080 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
22090 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
220a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
220b0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
220c0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
220d0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
220e0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
220f0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
22100 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
22110 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
22120 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
22130 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
22140 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
22150 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
22160 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
22170 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
22180 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
22190 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
221a0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
221b0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
221c0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
221d0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
221e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
221f0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
22200 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
22210 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
22220 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45  D: sqlite3.** KE
22230 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69  YWORDS: {authori
22240 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a  zer callback}.**
22250 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
22260 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
22270 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22280 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
22290 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
222a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
222b0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
222c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
222d0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
222e0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
222f0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
22300 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
22310 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
22320 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22330 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
22340 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
22350 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
22360 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22370 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
22380 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b  _prepare16()], [
22390 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
223a0 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  6_v2()],.** and 
223b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
223c0 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76  16_v3()].  ^At v
223d0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
223e0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
223f0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
22400 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
22410 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
22420 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
22430 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
22440 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22450 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
22460 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
22470 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
22480 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
22490 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
224a0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
224b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
224c0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
224d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
224e0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
224f0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
22500 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
22510 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22520 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
22530 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
22540 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
22550 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
22560 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
22570 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
22580 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
22590 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
225a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
225b0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
225c0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
225d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
225e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
225f0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
22600 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
22610 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22620 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
22630 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
22640 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
22650 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
22660 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
22670 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
22680 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
22690 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
226a0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
226b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
226c0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
226d0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
226e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
226f0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
22700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
22710 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
22720 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
22730 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
22740 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
22750 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
22760 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
22770 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
22780 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
22790 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
227a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
227b0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
227c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
227d0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
227e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
227f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
22800 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
22810 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
22820 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
22830 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
22840 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
22850 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
22860 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
22870 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
22880 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
22890 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
228a0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
228b0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
228c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
228d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
228e0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69   either NULL poi
228f0 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65  nters or zero-te
22900 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
22910 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  .** that contain
22920 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
22930 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
22940 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
22950 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63  rized..** Applic
22960 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61  ations must alwa
22970 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74  ys be prepared t
22980 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55  o encounter a NU
22990 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e  LL pointer in an
229a0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72  y.** of the thir
229b0 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69  d through the si
229c0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f  xth parameters o
229d0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  f the authorizat
229e0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
229f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
22a00 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
22a10 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
22a20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
22a30 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
22a40 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
22a50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22a60 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
22a70 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
22a80 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
22a90 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
22aa0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
22ab0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
22ac0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
22ad0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
22ae0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
22af0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
22b00 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
22b10 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
22b20 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
22b30 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
22b40 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
22b50 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
22b60 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68   a table..** ^Wh
22b70 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65  en a table is re
22b80 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53  ferenced by a [S
22b90 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f  ELECT] but no co
22ba0 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a  lumn values are.
22bb0 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  ** extracted fro
22bc0 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f  m that table (fo
22bd0 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71  r example in a q
22be0 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45  uery like.** "SE
22bf0 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52  LECT count(*) FR
22c00 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68  OM tab") then th
22c10 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  e [SQLITE_READ] 
22c20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22c30 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ack.** is invoke
22c40 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20  d once for that 
22c50 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c  table with a col
22c60 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73  umn name that is
22c70 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22c80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
22c90 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
22ca0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
22cb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
22cc0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
22cd0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
22ce0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
22cf0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
22d00 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
22d10 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
22d20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
22d30 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
22d40 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
22d50 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
22d60 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
22d70 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
22d80 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
22d90 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
22da0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
22db0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
22dc0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
22dd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
22de0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
22df0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
22e00 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
22e10 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
22e20 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
22e30 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
22e40 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
22e50 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
22e60 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
22e70 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
22e80 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
22e90 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
22ea0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
22eb0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
22ec0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
22ed0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
22ee0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
22ef0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
22f00 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
22f10 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
22f20 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
22f30 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
22f40 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
22f50 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
22f60 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
22f70 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
22f80 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
22f90 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
22fa0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
22fb0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
22fc0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
22fd0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
22fe0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
22ff0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
23000 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
23010 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
23020 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
23030 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
23040 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
23050 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
23060 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
23070 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
23080 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
23090 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
230a0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
230b0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
230c0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
230d0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
230e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
230f0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
23100 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
23110 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
23120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
23130 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
23140 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
23150 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
23160 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
23170 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
23180 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
23190 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
231a0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
231b0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
231c0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
231d0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
231e0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
231f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23200 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
23210 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
23220 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
23230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23240 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
23250 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
23260 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
23270 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23280 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23290 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
232a0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
232b0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
232c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
232d0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
232e0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
232f0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
23300 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
23310 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
23320 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
23330 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
23340 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
23350 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
23360 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
23370 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
23380 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
23390 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
233a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
233b0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
233c0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
233d0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
233e0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
233f0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
23400 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
23420 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
23430 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23440 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
23450 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
23460 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
23470 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
23480 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
23490 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
234a0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
234b0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
234c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
234d0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
234e0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
234f0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
23500 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
23510 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
23520 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
23530 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
23540 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
23550 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
23560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
23570 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
23580 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
23590 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
235a0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
235b0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
235c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
235d0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
235e0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
235f0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
23600 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
23610 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
23620 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23630 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
23640 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23650 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
23660 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
23670 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
23680 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
23690 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
236a0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
236b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
236c0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
236d0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
236e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
236f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
23700 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
23710 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
23720 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
23730 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
23740 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
23750 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
23760 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
23770 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
23780 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
23790 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
237a0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
237b0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
237c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
237d0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
237e0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
237f0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
23800 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
23810 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
23820 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
23830 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
23840 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
23850 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
23860 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
23870 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
23880 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
23890 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
238a0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
238b0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
238c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
238d0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
238e0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
238f0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
23900 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
23910 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
23920 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
23930 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
23940 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
23950 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
23960 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
23970 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
23980 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
23990 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
239a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
239b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
239c0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
239d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
239e0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
239f0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
23a00 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
23a10 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
23a20 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
23a30 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
23a40 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
23a50 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
23a60 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
23a70 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
23a80 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
23a90 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
23aa0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
23ab0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
23ac0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
23ad0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
23ae0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
23af0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23b00 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
23b10 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
23b20 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
23b30 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
23b40 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
23b50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23b60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23b70 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
23b80 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
23b90 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
23ba0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
23bb0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
23bc0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
23bd0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
23be0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
23bf0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
23c00 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
23c10 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
23c20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23c30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23c40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
23c50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
23c60 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
23c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
23c80 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
23c90 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
23ca0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
23cb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23cd0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
23ce0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
23cf0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23d00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23d10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23d20 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
23d30 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
23d40 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23d50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23d60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23d70 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
23d80 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
23d90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23da0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23db0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
23dc0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
23dd0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
23de0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
23df0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23e00 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
23e10 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
23e20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
23e30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23e40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23e50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
23e60 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
23e70 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23e80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23e90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23ea0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
23eb0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
23ec0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
23ed0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23ee0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23ef0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
23f00 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
23f10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23f20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23f30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23f40 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
23f50 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
23f60 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23f70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23f90 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
23fa0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
23fb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23fc0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23fd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23fe0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
23ff0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
24000 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
24010 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24030 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
24040 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
24050 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
24060 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24080 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
24090 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
240a0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
240b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
240c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
240d0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
240e0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
240f0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
24100 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
24120 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
24130 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
24140 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
24150 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
24160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24170 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
24180 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
24190 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
241a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
241b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
241c0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
241d0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
241e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
241f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24200 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
24210 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
24220 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
24230 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
24240 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
24250 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
24260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
24270 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
24280 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
24290 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
242a0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
242b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
242c0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
242d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
242e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
242f0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
24300 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
24310 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
24320 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24340 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
24350 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
24360 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24370 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
24380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24390 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
243a0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
243b0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
243c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
243d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
243e0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
243f0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
24400 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
24410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24430 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
24440 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
24450 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
24460 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24480 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
24490 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
244a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
244b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
244c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
244d0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
244e0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
244f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
24500 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24520 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
24530 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
24540 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
24550 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
24560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24570 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
24580 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
24590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
245a0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
245b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
245c0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
245d0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
245e0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
245f0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
24600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
24610 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
24620 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
24630 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
24640 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
24650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
24660 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
24670 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
24680 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
24690 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
246a0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
246b0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
246c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
246d0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
246e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
246f0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
24700 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
24710 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24720 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24730 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
24740 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
24750 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
24760 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
24770 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
24780 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
24790 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
247a0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
247b0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
247c0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
247d0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
247e0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
247f0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
24800 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
24810 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
24820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24830 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
24840 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24850 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
24860 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
24870 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
24880 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
24890 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
248a0 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
248b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
248c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
248d0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
248e0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
248f0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
24900 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
24910 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
24920 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
24930 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
24940 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24950 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
24960 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
24970 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
24980 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
24990 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
249a0 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
249b0 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
249c0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
249d0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
249e0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
249f0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
24a00 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
24a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
24a20 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
24a30 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
24a40 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
24a50 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
24a60 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
24a70 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
24a80 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
24a90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
24aa0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
24ab0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
24ac0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
24ad0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
24ae0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
24af0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
24b00 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
24b10 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
24b20 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
24b30 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
24b40 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
24b50 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
24b60 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
24b70 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
24b80 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
24b90 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
24ba0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
24bb0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
24bc0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
24bd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
24be0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
24bf0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
24c00 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
24c10 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
24c20 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
24c30 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
24c40 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
24c50 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
24c60 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
24c70 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
24c80 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
24c90 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
24ca0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
24cb0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
24cc0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
24cd0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
24ce0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
24cf0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
24d00 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
24d10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
24d20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
24d30 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
24d40 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
24d50 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72  3*,.   void(*xTr
24d60 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
24d70 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
24d80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
24d90 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
24da0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
24db0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
24dc0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
24dd0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
24de0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
24df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24e00 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
24e10 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
24e20 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
24e30 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
24e40 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
24e50 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
24e60 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
24e70 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
24e80 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
24e90 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
24ea0 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d  ng logic.  The M
24eb0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
24ec0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24ed0 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61  2(D,M,X,P)] is a
24ee0 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
24ef0 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
24f00 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
24f10 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
24f20 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
24f30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
24f40 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
24f50 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
24f60 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
24f70 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
24f80 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
24f90 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
24fa0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
24fb0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
24fc0 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
24fd0 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
24fe0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
24ff0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
25000 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
25010 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
25020 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
25030 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
25040 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
25050 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
25060 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
25070 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
25080 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
25090 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
250a0 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
250b0 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
250c0 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
250d0 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
250e0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
250f0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
25100 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
25110 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
25120 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
25130 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
25140 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
25150 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
25160 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
25170 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
25180 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
25190 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
251a0 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
251b0 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
251c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
251d0 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
251e0 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
251f0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
25200 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
25210 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
25220 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
25230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
25240 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
25250 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25260 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
25270 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
25280 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
25290 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
252a0 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
252b0 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
252c0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
252d0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
252e0 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
252f0 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
25300 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
25310 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
25320 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
25330 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
25340 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
25350 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
25360 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
25370 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
25380 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
25390 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
253a0 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
253b0 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
253c0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
253d0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
253e0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
253f0 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
25400 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
25410 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
25420 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
25430 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
25440 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
25450 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
25460 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
25470 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
25480 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
25490 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
254a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
254b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
254c0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
254d0 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
254e0 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
254f0 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
25500 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
25510 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
25520 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
25530 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
25540 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
25550 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
25560 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
25570 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
25580 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
25590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
255a0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
255b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
255c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
255d0 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
255e0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
255f0 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
25600 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
25610 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
25620 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
25630 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
25640 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
25650 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
25660 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25670 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
25680 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
25690 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
256a0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
256b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
256c0 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
256d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
256e0 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
256f0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
25700 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
25710 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
25720 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
25730 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
25740 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
25750 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
25760 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
25770 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
25780 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
25790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
257a0 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
257b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
257c0 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
257d0 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
257e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
257f0 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
25800 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25810 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
25820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
25830 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
25840 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
25850 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
25860 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
25870 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
25880 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
25890 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
258a0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
258b0 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
258c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
258d0 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
258e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
258f0 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
25900 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
25910 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
25920 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
25930 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
25940 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
25950 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
25960 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
25970 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
25980 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
25990 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
259a0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
259b0 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
259c0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
259d0 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
259e0 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
259f0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
25a00 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
25a10 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
25a20 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
25a30 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
25a40 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
25a50 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
25a60 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
25a70 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
25a80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
25a90 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
25aa0 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
25ab0 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
25ac0 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
25ad0 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
25ae0 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
25af0 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
25b00 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
25b10 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
25b20 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
25b30 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
25b40 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
25b50 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
25b60 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
25b70 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
25b80 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
25b90 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
25ba0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
25bb0 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
25bc0 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
25bd0 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
25be0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
25bf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
25c00 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
25c10 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
25c20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
25c30 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
25c40 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
25c50 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
25c60 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
25c70 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
25c80 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
25c90 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
25ca0 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
25cb0 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
25cc0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
25ce0 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
25cf0 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
25d00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
25d10 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
25d20 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
25d30 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
25d40 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
25d50 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  ecated..*/.int s
25d60 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25d70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75  .  sqlite3*,.  u
25d80 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20  nsigned uMask,. 
25d90 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29   int(*xCallback)
25da0 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c  (unsigned,void*,
25db0 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20  void*,void*),.  
25dc0 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f  void *pCtx.);../
25dd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
25de0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
25df0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
25e00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
25e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
25e20 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
25e30 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
25e40 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
25e50 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
25e60 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
25e70 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
25e80 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
25e90 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
25ea0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
25eb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25ec0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
25ed0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
25ee0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
25ef0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
25f00 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
25f10 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
25f20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
25f30 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
25f40 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
25f50 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
25f60 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
25f70 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
25f80 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
25f90 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
25fa0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
25fb0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
25fc0 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
25fd0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
25fe0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
25ff0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
26000 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
26010 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
26020 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
26030 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
26040 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
26050 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
26060 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
26070 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
26080 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
26090 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
260a0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
260b0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
260c0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
260d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
260e0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
260f0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
26100 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
26110 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
26120 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
26130 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
26140 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
26150 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
26160 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
26170 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
26180 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
26190 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
261a0 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
261b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
261c0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
261d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
261e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
261f0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
26200 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
26210 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
26220 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
26230 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
26240 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
26250 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
26260 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
26270 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
26280 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
26290 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
262a0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
262b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
262c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
262d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
262e0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
262f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26300 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
26310 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
26320 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
26330 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
26340 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
26350 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
26360 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
26370 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
26380 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
26390 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
263a0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
263b0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
263c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
263d0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
263e0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
263f0 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
26400 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
26410 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
26420 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
26430 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
26440 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
26450 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
26460 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
26470 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
26480 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
26490 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
264a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
264b0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
264c0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
264d0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
264e0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
264f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
26500 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
26510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
26520 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
26530 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
26540 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
26550 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
26560 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
26570 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
26580 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
26590 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
265a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
265b0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
265c0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
265d0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
265e0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
265f0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
26600 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
26610 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
26620 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26630 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
26640 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
26650 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
26660 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
26670 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
26680 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
26690 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
266a0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
266b0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
266c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
266d0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
266e0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
266f0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
26700 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
26710 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
26720 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
26730 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
26740 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
26750 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
26760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
26770 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
26780 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
26790 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
267a0 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
267b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
267c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
267d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
267e0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
267f0 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
26800 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
26810 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
26820 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
26830 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
26840 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
26850 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
26860 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
26870 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
26880 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
26890 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
268a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
268b0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
268c0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
268d0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
268e0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
268f0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
26900 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
26910 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
26920 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
26930 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
26940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
26950 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
26960 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
26970 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
26980 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
26990 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
269a0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
269b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
269c0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
269d0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
269e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
269f0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
26a00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
26a10 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
26a20 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
26a30 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
26a40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
26a50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
26a60 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
26a70 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
26a80 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
26a90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
26aa0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
26ab0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
26ac0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
26ad0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
26ae0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
26af0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
26b00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26b10 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
26b20 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
26b30 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
26b40 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
26b50 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
26b60 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
26b70 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
26b80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
26b90 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
26ba0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
26bb0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
26bc0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
26bd0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
26be0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
26bf0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
26c00 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
26c10 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
26c20 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
26c30 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
26c40 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
26c50 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
26c60 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
26c70 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
26c80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
26c90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26ca0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
26cb0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
26cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
26cd0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26ce0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
26cf0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
26d00 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
26d10 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
26d20 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
26d30 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
26d40 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
26d50 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
26d60 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
26d70 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
26d80 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
26d90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
26da0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26db0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26dc0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
26dd0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
26de0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
26df0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
26e00 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
26e10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26e20 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
26e30 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
26e40 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26e50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
26e60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
26e70 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
26e80 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
26e90 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
26ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
26eb0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
26ec0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
26ed0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
26ee0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
26ef0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
26f00 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
26f10 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
26f20 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
26f30 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
26f40 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
26f50 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
26f60 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
26f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
26f80 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
26f90 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
26fa0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
26fb0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
26fc0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
26fd0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
26fe0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
26ff0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
27000 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
27010 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
27020 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
27030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
27040 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
27050 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
27060 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
27070 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
27080 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
27090 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
270a0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
270b0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
270c0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
270d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
270e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
270f0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
27100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27110 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
27120 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
27130 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
27140 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
27150 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
27160 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27170 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
27180 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
27190 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
271a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
271b0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
271c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
271d0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
271e0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
271f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27200 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
27210 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
27220 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
27230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
27240 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
27250 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
27260 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
27270 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
27280 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
27290 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
272a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
272b0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
272c0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
272d0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
272e0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
272f0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
27300 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
27310 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27320 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
27330 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
27340 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
27350 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
27360 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
27370 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
27380 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
27390 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
273a0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
273b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
273c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
273d0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
273e0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
273f0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
27400 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
27410 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
27420 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
27430 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
27440 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
27450 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
27460 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
27470 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
27480 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
27490 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
274a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
274b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
274c0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
274d0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
274e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
274f0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
27500 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
27510 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
27520 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
27530 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
27540 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
27550 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
27560 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
27570 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
27580 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
27590 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
275a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
275b0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
275c0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
275d0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
275e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
275f0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
27600 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
27610 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
27620 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
27630 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
27640 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
27650 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
27660 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27670 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
27680 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
27690 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
276a0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
276b0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
276c0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
276d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
276e0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
276f0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
27700 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
27710 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66  option..** URI f
27720 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
27730 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
27740 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
27750 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
27760 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
27770 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
27780 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
27790 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
277a0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
277b0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
277c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
277d0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
277e0 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
277f0 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
27800 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
27810 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
27820 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
27830 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
27840 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
27850 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
27860 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
27870 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
27880 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
27890 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
278a0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
278b0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
278c0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
278d0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
278e0 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
278f0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
27900 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
27910 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
27920 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
27930 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
27940 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
27950 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
27960 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
27970 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
27980 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
27990 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
279a0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
279b0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
279c0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
279d0 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
279e0 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
279f0 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
27a00 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
27a10 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
27a20 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
27a30 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
27a40 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
27a50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
27a60 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
27a70 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
27a80 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
27a90 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
27aa0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
27ab0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
27ac0 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
27ad0 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
27ae0 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
27af0 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
27b00 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
27b10 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
27b20 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
27b30 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
27b40 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
27b50 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
27b60 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
27b70 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
27b80 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
27b90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
27ba0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
27bb0 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
27bc0 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
27bd0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
27be0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
27bf0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
27c00 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
27c10 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
27c20 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
27c30 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
27c40 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
27c50 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
27c60 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
27c70 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
27c80 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
27c90 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
27ca0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
27cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27cc0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
27cd0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
27ce0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
27cf0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
27d00 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
27d10 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
27d20 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
27d30 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
27d40 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
27d50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27d60 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
27d70 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
27d80 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
27d90 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
27da0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
27db0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
27dc0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
27dd0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
27de0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
27df0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
27e00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27e10 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
27e20 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
27e30 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
27e40 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
27e50 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
27e60 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
27e70 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
27e80 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
27e90 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
27ea0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
27eb0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
27ec0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
27ed0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
27ee0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27ef0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
27f00 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
27f10 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
27f20 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
27f30 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
27f40 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
27f50 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
27f60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
27f70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
27f80 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
27f90 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
27fa0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
27fb0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
27fc0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
27fd0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
27fe0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
27ff0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
28000 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
28010 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
28020 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
28030 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
28040 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
28050 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
28060 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
28070 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
28080 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
28090 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
280a0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
280b0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
280c0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
280d0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
280e0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
280f0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
28100 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
28110 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
28120 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
28130 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
28140 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
28150 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
28160 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
28170 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
28180 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
28190 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
281a0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
281b0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
281c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
281d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
281e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
281f0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
28200 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
28210 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
28220 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
28230 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
28240 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
28250 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
28260 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
28270 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
28280 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
28290 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
282a0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
282b0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
282c0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
282d0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
282e0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
282f0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
28300 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
28310 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28320 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
28330 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
28340 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
28350 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28360 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
28370 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
28380 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
28390 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
283a0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
283b0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
283c0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
283d0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
283e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
283f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
28400 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
28410 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
28420 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
28430 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
28440 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
28450 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
28460 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
28470 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
28480 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
28490 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
284a0 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
284b0 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
284c0 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
284d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
284e0 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
284f0 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
28500 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
28510 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
28520 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
28530 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
28540 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
28550 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
28560 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
28570 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
28580 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
28590 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
285a0 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
285b0 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
285c0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
285d0 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
285e0 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
285f0 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
28600 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
28610 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
28620 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
28630 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
28640 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
28650 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
28660 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
28670 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
28680 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
28690 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
286a0 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
286b0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
286c0 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
286d0 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
286e0 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
286f0 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
28700 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
28710 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
28720 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
28730 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
28740 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28750 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
28760 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
28770 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
28780 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
28790 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
287a0 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
287b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
287c0 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
287d0 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
287e0 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
287f0 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
28800 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
28810 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
28820 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
28830 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
28840 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
28850 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
28860 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
28870 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
28880 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
28890 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
288a0 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
288b0 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
288c0 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
288d0 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
288e0 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
288f0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
28900 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
28910 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
28920 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
28930 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
28940 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
28950 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
28960 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
28970 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
28980 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
28990 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
289a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
289b0 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
289c0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
289d0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
289e0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
289f0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
28a00 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
28a10 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
28a20 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
28a30 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
28a40 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
28a50 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
28a60 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
28a70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
28a80 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
28a90 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
28aa0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
28ab0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
28ac0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
28ad0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
28ae0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
28af0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
28b00 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
28b10 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
28b20 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
28b30 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
28b40 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
28b50 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
28b60 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
28b70 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
28b80 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
28b90 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
28ba0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
28bb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
28bc0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
28bd0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
28be0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
28bf0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
28c00 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
28c10 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
28c20 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
28c30 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
28c40 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
28c50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
28c60 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
28c70 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
28c80 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
28c90 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
28ca0 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
28cb0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
28cc0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
28cd0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
28ce0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
28cf0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
28d00 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
28d10 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
28d20 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
28d30 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
28d40 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
28d50 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
28d60 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
28d70 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
28d80 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
28d90 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
28da0 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
28db0 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
28dc0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
28dd0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
28de0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
28df0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
28e00 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
28e10 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
28e20 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
28e30 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
28e40 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
28e50 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
28e60 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
28e70 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
28e80 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
28e90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28ea0 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
28eb0 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
28ec0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
28ed0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28ee0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
28ef0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
28f00 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
28f10 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
28f20 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
28f30 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
28f40 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
28f50 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
28f60 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
28f70 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
28f80 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
28f90 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
28fa0 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
28fb0 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
28fc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
28fd0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
28fe0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
28ff0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
29000 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
29010 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
29020 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
29030 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
29040 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
29050 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
29060 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
29070 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
29080 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
29090 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
290a0 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
290b0 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
290c0 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
290d0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
290e0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
290f0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
29100 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
29110 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
29120 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
29130 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
29140 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
29150 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
29160 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
29170 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
29180 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
29190 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
291a0 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
291b0 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
291c0 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
291d0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
291e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
291f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
29200 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
29210 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
29220 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
29230 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
29240 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
29250 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
29260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29270 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
29280 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
29290 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
292a0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
292b0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
292c0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
292d0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
292e0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
292f0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
29300 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
29310 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
29320 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
29330 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
29340 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
29350 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
29360 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
29370 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
29380 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
29390 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
293a0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
293b0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
293c0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
293d0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
293e0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
293f0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
29400 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
29410 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
29420 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29430 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
29440 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
29450 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
29460 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
29470 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
29480 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
29490 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
294a0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
294b0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
294c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
294d0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
294e0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
294f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
29500 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29510 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
29520 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
29530 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
29540 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
29550 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
29560 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
29570 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
29580 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
29590 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
295a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
295b0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
295c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
295d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
295e0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
295f0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
29600 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
29610 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
29620 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
29630 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
29640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
29650 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
29660 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
29670 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
29680 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
29690 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
296a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
296b0 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
296c0 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
296d0 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
296e0 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
296f0 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
29700 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
29710 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
29720 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
29730 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
29740 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
29750 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
29760 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
29770 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
29780 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
29790 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
297a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
297b0 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
297c0 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
297d0 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
297e0 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
297f0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
29800 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
29810 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
29820 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
29830 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
29840 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
29850 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
29860 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
29870 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
29880 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
29890 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
298a0 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
298b0 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
298c0 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
298d0 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
298e0 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
298f0 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
29900 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
29910 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
29920 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
29930 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
29940 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
29950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
29960 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
29970 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29980 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
29990 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
299a0 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
299b0 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
299c0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
299d0 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
299e0 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
299f0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
29a00 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
29a10 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29a20 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
29a30 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
29a40 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
29a50 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
29a60 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
29a70 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
29a80 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
29a90 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
29aa0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
29ab0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
29ac0 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
29ad0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
29ae0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
29af0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
29b00 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
29b10 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
29b20 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
29b30 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
29b40 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
29b50 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
29b60 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
29b70 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
29b80 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
29b90 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
29ba0 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
29bb0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
29bc0 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
29bd0 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
29be0 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
29bf0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
29c00 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
29c10 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
29c20 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
29c30 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
29c40 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
29c50 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
29c60 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
29c70 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
29c80 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
29c90 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
29ca0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
29cb0 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
29cc0 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
29cd0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
29ce0 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
29cf0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
29d00 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
29d10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29d20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
29d30 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
29d40 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
29d50 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
29d60 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29d70 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
29d80 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
29d90 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
29da0 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
29db0 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
29dc0 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
29dd0 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
29de0 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
29df0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
29e00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
29e10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
29e20 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29e30 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
29e40 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
29e50 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
29e60 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
29e70 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
29e80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
29e90 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
29ea0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
29eb0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
29ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
29ed0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
29ee0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
29ef0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
29f00 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
29f10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
29f20 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
29f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
29f40 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
29f50 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
29f60 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
29f70 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
29f80 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
29f90 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
29fa0 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
29fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29fc0 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
29fd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
29fe0 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
29ff0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
2a000 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
2a010 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
2a020 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
2a030 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
2a040 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73   call..** ^The s
2a050 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
2a060 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
2a070 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
2a080 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
2a090 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2a0a0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
2a0b0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
2a0c0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
2a0d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
2a0e0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
2a0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
2a100 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2a110 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
2a120 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2a130 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
2a140 64 65 28 29 20 6d 69 67 68 74 20 63 68 61 6e 67  de() might chang
2a150 65 20 77 69 74 68 20 65 61 63 68 20 41 50 49 20  e with each API 
2a160 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c  call..** Except,
2a170 20 74 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20   there are some 
2a180 69 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  interfaces that 
2a190 61 72 65 20 67 75 61 72 61 6e 74 65 65 64 20 74  are guaranteed t
2a1a0 6f 20 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67  o never.** chang
2a1b0 65 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  e the value of t
2a1c0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20  he error code.  
2a1d0 54 68 65 20 65 72 72 6f 72 2d 63 6f 64 65 20 70  The error-code p
2a1e0 72 65 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74  reserving.** int
2a1f0 65 72 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a  erfaces are:.**.
2a200 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2a210 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a220 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2a230 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
2a240 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  de().** <li> sql
2a250 69 74 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a  ite3_errmsg().**
2a260 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72   <li> sqlite3_er
2a270 72 6d 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c  rmsg16().** </ul
2a280 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  >.**.** ^The sql
2a290 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
2a2a0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
2a2b0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
2a2c0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
2a2d0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
2a2e0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
2a2f0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2a300 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
2a310 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
2a320 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
2a330 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
2a340 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
2a350 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
2a360 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
2a370 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
2a380 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
2a390 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
2a3a0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
2a3b0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
2a3c0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
2a3d0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
2a3e0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
2a3f0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
2a400 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2a410 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
2a420 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a430 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
2a440 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2a450 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
2a460 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
2a470 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
2a480 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
2a490 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
2a4a0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
2a4b0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
2a4c0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
2a4d0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
2a4e0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
2a4f0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2a500 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
2a510 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
2a520 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2a530 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
2a540 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
2a550 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
2a560 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
2a570 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
2a580 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
2a590 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
2a5a0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
2a5b0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
2a5c0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
2a5d0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
2a5e0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
2a5f0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
2a600 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
2a610 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
2a620 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
2a630 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2a640 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
2a650 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
2a660 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
2a670 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
2a680 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
2a690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
2a6a0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
2a6b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
2a6c0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
2a6d0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
2a6e0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
2a6f0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
2a700 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
2a710 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
2a720 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
2a730 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
2a740 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
2a750 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
2a760 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
2a770 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
2a780 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2a790 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
2a7a0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
2a7b0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
2a7c0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
2a7d0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
2a7e0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
2a7f0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
2a800 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
2a810 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
2a820 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
2a830 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
2a840 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
2a850 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
2a860 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
2a870 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
2a880 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a890 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
2a8a0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
2a8b0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
2a8c0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
2a8d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a8e0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
2a8f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
2a900 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2a910 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
2a920 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
2a930 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
2a940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
2a950 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
2a960 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
2a970 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
2a980 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
2a990 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
2a9a0 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
2a9b0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
2a9c0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
2a9d0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
2a9e0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
2a9f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
2aa00 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
2aa10 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
2aa20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
2aa30 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
2aa40 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
2aa50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2aa60 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
2aa70 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
2aa80 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
2aa90 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2aaa0 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
2aab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
2aac0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
2aad0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
2aae0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
2aaf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ab00 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
2ab10 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
2ab20 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2ab30 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
2ab40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ab50 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
2ab60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ab70 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
2ab80 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
2ab90 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
2aba0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2abb0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
2abc0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
2abd0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
2abe0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2abf0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
2ac00 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
2ac10 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
2ac20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac30 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ac40 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
2ac50 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
2ac60 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
2ac70 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
2ac80 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
2ac90 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
2aca0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2acb0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
2acc0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
2acd0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2ace0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
2acf0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
2ad00 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
2ad10 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
2ad20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
2ad30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
2ad40 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
2ad50 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
2ad60 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
2ad70 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
2ad80 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
2ad90 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
2ada0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2adb0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
2adc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2add0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
2ade0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
2adf0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
2ae00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2ae10 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
2ae20 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
2ae30 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
2ae40 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
2ae50 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
2ae60 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
2ae70 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
2ae80 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
2ae90 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
2aea0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
2aeb0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
2aec0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
2aed0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
2aee0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
2aef0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
2af00 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
2af10 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
2af20 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
2af30 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
2af40 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
2af50 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
2af60 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
2af70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
2af80 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
2af90 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
2afa0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
2afb0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
2afc0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
2afd0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
2afe0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
2aff0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
2b000 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
2b010 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
2b020 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
2b030 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
2b040 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2b050 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
2b060 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2b070 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
2b080 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
2b090 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
2b0a0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
2b0b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
2b0c0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
2b0d0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
2b0e0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
2b0f0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
2b100 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
2b110 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
2b120 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
2b130 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
2b140 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
2b150 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
2b160 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
2b170 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
2b180 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
2b190 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2b1a0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
2b1b0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
2b1c0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
2b1d0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
2b1e0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
2b1f0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
2b200 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
2b210 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
2b220 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
2b230 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
2b240 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
2b250 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
2b260 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
2b270 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
2b280 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
2b290 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
2b2a0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
2b2b0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
2b2c0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
2b2d0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
2b2e0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
2b2f0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
2b300 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
2b310 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
2b320 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
2b330 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
2b340 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
2b350 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
2b360 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
2b370 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
2b380 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
2b390 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
2b3a0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
2b3b0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
2b3c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
2b3d0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
2b3e0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
2b3f0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
2b400 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
2b410 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2b420 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
2b430 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
2b440 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
2b450 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
2b460 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
2b470 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
2b480 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
2b490 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2b4a0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2b4b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2b4c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b4d0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
2b4e0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
2b4f0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
2b500 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2b510 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
2b520 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
2b530 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
2b540 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
2b550 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
2b560 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2b570 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
2b580 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
2b590 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
2b5a0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
2b5b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
2b5c0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
2b5d0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
2b5e0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
2b5f0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
2b600 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
2b610 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
2b620 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
2b630 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
2b640 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
2b650 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
2b660 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2b670 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2b680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b690 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2b6a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
2b6b0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
2b6c0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
2b6d0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
2b6e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b6f0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2b700 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2b710 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2b720 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2b730 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2b740 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
2b750 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
2b760 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2b770 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2b780 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
2b790 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2b7a0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
2b7b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2b7c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2b7d0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
2b7e0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
2b7f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2b800 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
2b810 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2b820 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
2b830 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
2b840 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
2b850 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
2b860 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b870 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2b880 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2b890 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2b8a0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2b8b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2b8c0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
2b8d0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
2b8e0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
2b8f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b900 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2b910 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
2b920 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b930 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
2b940 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b950 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
2b960 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
2b970 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
2b980 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b990 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2b9a0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
2b9b0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2b9c0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
2b9d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2b9e0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
2b9f0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
2ba00 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
2ba10 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2ba20 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
2ba30 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ent.  If [sqlite
2ba40 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ba50 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61  or.** the equiva
2ba60 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c  lent tries to al
2ba70 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72  locate space for
2ba80 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20   more than this 
2ba90 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  many opcodes.** 
2baa0 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70  in a single prep
2bab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
2bac0 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  an SQLITE_NOMEM 
2bad0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2bae0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
2baf0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
2bb00 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
2bb10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bb20 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
2bb30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2bb40 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2bb50 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
2bb60 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
2bb70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2bb80 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
2bb90 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2bba0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
2bbb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2bbc0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
2bbd0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
2bbe0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
2bbf0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
2bc00 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2bc10 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
2bc20 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2bc30 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2bc40 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
2bc50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2bc60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
2bc70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
2bc80 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
2bc90 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
2bca0 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
2bcb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bcc0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2bcd0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
2bce0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2bcf0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
2bd00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2bd10 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
2bd20 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
2bd30 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
2bd40 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
2bd50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
2bd60 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
2bd70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bd80 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
2bd90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2bda0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2bdb0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
2bdc0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
2bdd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2bde0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2bdf0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
2be00 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2be10 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
2be20 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2be30 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
2be40 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
2be50 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
2be60 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2be70 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
2be80 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
2be90 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2bea0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2beb0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2bec0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
2bed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2bee0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2bef0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2bf00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2bf10 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
2bf20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2bf30 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
2bf40 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
2bf50 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2bf60 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
2bf70 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
2bf80 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
2bf90 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bfa0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
2bfb0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
2bfc0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2bfd0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
2bfe0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
2bff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c000 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
2c010 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
2c020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c030 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2c040 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
2c050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c060 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2c070 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
2c080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c090 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2c0a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
2c0b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c0c0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2c0d0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
2c0e0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
2c0f0 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73  F: Prepare Flags
2c100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2c110 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2c120 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74  rious flags that
2c130 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69   can be passed i
2c140 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67  nto.** "prepFlag
2c150 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  s" parameter of 
2c160 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2c170 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a  pare_v3()] and.*
2c180 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c190 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72  re16_v3()] inter
2c1a0 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  faces..**.** New
2c1b0 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64   flags may be ad
2c1c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2c1d0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2c1e0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2c1f0 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2c200 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28  _PERSISTENT]] ^(
2c210 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2c220 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64  RE_PERSISTENT</d
2c230 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
2c240 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2c250 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20  SISTENT flag is 
2c260 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75  a hint to the qu
2c270 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74  ery planner.** t
2c280 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2c290 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2c2a0 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  be retained for 
2c2b0 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a  a long time and.
2c2c0 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73  ** probably reus
2c2d0 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e  ed many times.)^
2c2e0 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66   ^Without this f
2c2f0 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  lag, [sqlite3_pr
2c300 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61  epare_v3()].** a
2c310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2c320 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75  are16_v3()] assu
2c330 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70  me that the prep
2c340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2c350 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20  ill .** be used 
2c360 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20  just once or at 
2c370 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73  most a few times
2c380 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f   and then destro
2c390 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
2c3a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c3b0 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f  ] relatively soo
2c3c0 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69  n. The current i
2c3d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63  mplementation ac
2c3e0 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69  ts.** on this hi
2c3f0 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74  nt by avoiding t
2c400 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61  he use of [looka
2c410 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20  side memory] so 
2c420 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70  as not to.** dep
2c430 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64  lete the limited
2c440 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73   store of lookas
2c450 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75  ide memory. Futu
2c460 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a  re versions of.*
2c470 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74  * SQLite may act
2c480 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69   on this hint di
2c490 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a  fferently..**.**
2c4a0 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52   [[SQLITE_PREPAR
2c4b0 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20 5e 28  E_NORMALIZE]] ^(
2c4c0 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2c4d0 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74  RE_NORMALIZE</dt
2c4e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
2c4f0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2c500 41 4c 49 5a 45 20 66 6c 61 67 20 69 6e 64 69 63  ALIZE flag indic
2c510 61 74 65 73 20 74 68 61 74 20 61 20 6e 6f 72 6d  ates that a norm
2c520 61 6c 69 7a 65 64 0a 2a 2a 20 72 65 70 72 65 73  alized.** repres
2c530 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2c540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 68  SQL statement sh
2c550 6f 75 6c 64 20 62 65 20 63 61 6c 63 75 6c 61 74  ould be calculat
2c560 65 64 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 61  ed and then.** a
2c570 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2c580 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2c590 65 6d 65 6e 74 2c 20 77 68 69 63 68 20 63 61 6e  ement, which can
2c5a0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 76 69 61   be obtained via
2c5b0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2c5c0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2c5d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
2c5e0 68 65 20 73 65 6d 61 6e 74 69 63 73 20 75 73 65  he semantics use
2c5f0 64 20 74 6f 0a 2a 2a 20 6e 6f 72 6d 61 6c 69 7a  d to.** normaliz
2c600 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e a SQL statemen
2c610 74 20 61 72 65 20 75 6e 73 70 65 63 69 66 69 65  t are unspecifie
2c620 64 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f  d and subject to
2c630 20 63 68 61 6e 67 65 2e 0a 2a 2a 20 41 74 20 61   change..** At a
2c640 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 72 61   minimum, litera
2c650 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c 20 62 65  l values will be
2c660 20 72 65 70 6c 61 63 65 64 20 77 69 74 68 20 73   replaced with s
2c670 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 63 65  uitable.** place
2c680 68 6f 6c 64 65 72 73 2e 0a 2a 2a 20 3c 2f 64 6c  holders..** </dl
2c690 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2c6a0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2c6b0 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20  ISTENT          
2c6c0 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65      0x01.#define
2c6d0 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2c6e0 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20 20 20 20  NORMALIZE       
2c6f0 20 20 20 20 20 20 20 20 30 78 30 32 0a 0a 2f 2a          0x02../*
2c700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c710 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2c720 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2c730 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2c740 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2c750 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c760 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2c770 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c780 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2c790 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2c7a0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2c7b0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2c7c0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2c7d0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2c7e0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2c7f0 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68  nes.  Or, in oth
2c800 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20  er words, these 
2c810 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2c820 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72  constructors for
2c830 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c840 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
2c850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66  ..**.** The pref
2c860 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f  erred routine to
2c870 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33   use is [sqlite3
2c880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20  _prepare_v2()]. 
2c890 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2c8a0 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65  _prepare()] inte
2c8b0 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20  rface is legacy 
2c8c0 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76  and should be av
2c8d0 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  oided..** [sqlit
2c8e0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2c8f0 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70   has an extra "p
2c900 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e  repFlags" option
2c910 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a   that is used.**
2c920 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72   for special pur
2c930 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  poses..**.** The
2c940 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d   use of the UTF-
2c950 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  8 interfaces is 
2c960 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51  preferred, as SQ
2c970 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a  Lite currently.*
2c980 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69  * does all parsi
2c990 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20  ng using UTF-8. 
2c9a0 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2c9b0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
2c9c0 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76  ded.** as a conv
2c9d0 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54  enience.  The UT
2c9e0 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2c9f0 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69  work by converti
2ca00 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  ng the.** input 
2ca10 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c  text into UTF-8,
2ca20 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74   then invoking t
2ca30 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2ca40 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2ca50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2ca60 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2ca70 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2ca80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2ca90 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2caa0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2cab0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2cac0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2cad0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2cae0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2caf0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2cb00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cb10 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2cb20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2cb30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2cb40 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2cb50 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2cb60 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2cb70 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2cb80 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2cb90 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2cba0 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73  te3_prepare(), s
2cbb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2cbc0 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2cbd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2cbe0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
2cbf0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
2cc00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2cc10 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2cc20 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2cc30 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2cc40 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46  e16_v3() use UTF
2cc50 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2cc60 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2cc70 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2cc80 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2cc90 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2cca0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2ccb0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2ccc0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2ccd0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2cce0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2ccf0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2cd00 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2cd10 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2cd20 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2cd30 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2cd40 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2cd50 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2cd60 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2cd70 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2cd80 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2cd90 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2cda0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2cdb0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2cdc0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2cdd0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2cde0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cdf0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2ce00 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2ce10 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2ce20 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2ce30 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2ce40 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2ce50 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2ce60 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2ce70 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2ce80 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2ce90 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2cea0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2ceb0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2cec0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2ced0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2cee0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2cef0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2cf00 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2cf10 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2cf20 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2cf30 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2cf40 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2cf50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf60 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2cf70 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2cf80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2cf90 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2cfa0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2cfb0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2cfc0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2cfd0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2cfe0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2cff0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2d000 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2d010 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2d020 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2d030 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2d040 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2d050 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2d060 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2d070 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2d080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2d090 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2d0a0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2d0b0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2d0c0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2d0d0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2d0e0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2d0f0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2d100 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2d110 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2d120 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2d130 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2d140 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2d150 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2d160 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2d170 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c  repare_v2(), sql
2d180 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2d190 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2d1a0 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2d1b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2d1c0 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61  e16_v3() interfa
2d1d0 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e  ces are recommen
2d1e0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2d1f0 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65  programs..** The
2d200 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2d210 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s (sqlite3_prepa
2d220 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
2d230 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a  _prepare16()).**
2d240 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
2d250 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2d260 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2d270 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2d280 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2d290 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
2d2a0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2d2b0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2d2c0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2d2d0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2d2e0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2d2f0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2d300 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2d310 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2d320 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2d330 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2d340 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2d350 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2d360 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2d370 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2d380 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d390 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2d3a0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2d3b0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2d3c0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2d3d0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2d3e0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2d3f0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2d400 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2d410 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2d420 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2d430 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2d440 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2d450 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2d460 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2d470 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2d480 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d490 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2d4a0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2d4b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2d4c0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2d4d0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2d4e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2d4f0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2d500 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2d510 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2d520 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2d530 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2d540 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2d550 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2d560 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2d570 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2d580 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2d590 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2d5a0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2d5b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2d5c0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2d5d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2d5e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d5f0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2d600 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2d610 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2d620 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2d630 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2d640 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2d650 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2d660 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2d670 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2d680 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2d690 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2d6a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2d6b0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2d6c0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2d6d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2d6e0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2d6f0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2d700 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2d710 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2d720 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2d730 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2d740 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2d750 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2d760 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2d770 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2d780 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2d790 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2d7a0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2d7b0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2d7c0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2d7d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2d7e0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2d7f0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2d800 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2d810 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2d820 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2d830 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2d840 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2d850 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2d860 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2d870 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2d880 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2d890 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2d8a0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2d8b0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2d8c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2d8d0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2d8e0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2d8f0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2d900 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2d910 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2d920 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2d930 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
2d940 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2d950 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2d960 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2d970 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2d980 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2d990 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2d9a0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2d9b0 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2d9c0 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2d9d0 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2d9e0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2d9f0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2da00 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2da10 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2da20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2da30 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2da40 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2da50 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2da60 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2da70 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2da80 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2da90 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  rameter..*/.int 
2daa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2dab0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2dac0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2dad0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2dae0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2daf0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2db00 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2db10 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2db20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2db30 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2db40 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2db50 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2db60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2db70 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2db80 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2db90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2dba0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2dbb0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2dbc0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2dbd0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2dbe0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2dbf0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2dc00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2dc10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2dc20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2dc30 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2dc40 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2dc50 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2dc60 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2dc70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2dc80 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2dc90 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2dca0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2dcb0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2dcc0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2dcd0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2dce0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2dcf0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2dd00 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2dd10 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2dd20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2dd30 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73  _prepare_v3(.  s
2dd40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2dd50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2dd60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2dd70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2dd80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2dd90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2dda0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2ddb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2ddc0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ddd0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2dde0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2ddf0 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2de00 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2de10 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2de20 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2de30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2de40 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2de50 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2de60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2de70 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2de80 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2de90 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2dea0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2deb0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2dec0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2ded0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2dee0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2def0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2df00 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2df10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2df20 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2df30 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2df40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2df50 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2df60 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2df70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2df80 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2df90 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2dfa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2dfb0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2dfc0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2dfd0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2dfe0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2dff0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e000 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
2e010 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e020 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e030 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e040 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2e050 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e060 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2e070 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2e080 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2e090 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2e0a0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2e0b0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2e0c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2e0d0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2e0e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2e0f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e100 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2e110 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2e120 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2e130 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2e140 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e150 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  16_v3(.  sqlite3
2e160 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e170 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2e180 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2e190 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2e1a0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2e1b0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2e1c0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2e1d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2e1e0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2e1f0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2e200 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2e210 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2e220 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2e230 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2e240 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2e250 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2e260 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2e270 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2e280 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2e290 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2e2a0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2e2b0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2e2c0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2e2d0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2e2e0 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2e2f0 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2e300 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e310 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2e320 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2e330 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e340 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2e350 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2e360 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2e370 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2e380 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2e390 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2e3a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e3b0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2e3c0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
2e3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e3e0 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
2e3f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e400 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54  e16_v3()]..** ^T
2e410 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2e420 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  ded_sql(P) inter
2e430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e440 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2e450 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2e460 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74  aining the SQL t
2e470 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2e480 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68  statement P with
2e490 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d  .** [bound param
2e4a0 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e  eters] expanded.
2e4b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e4c0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2e4d0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e4e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e4f0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2e500 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2e510 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51  he normalized SQ
2e520 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2e530 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20  ed statement P. 
2e540 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63   The.** semantic
2e550 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c  s used to normal
2e560 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d  ize a SQL statem
2e570 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66  ent are unspecif
2e580 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a  ied and subject.
2e590 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41  ** to change.  A
2e5a0 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74  t a minimum, lit
2e5b0 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c  eral values will
2e5c0 20 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74   be replaced wit
2e5d0 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c  h suitable.** pl
2e5e0 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a  aceholders..**.*
2e5f0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2e600 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2e610 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2e620 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2e630 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2e640 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2e650 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2e660 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2e670 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2e680 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2e690 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2e6a0 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2e6b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2e6c0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2e6d0 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2e6e0 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2e6f0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2e700 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2e710 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2e720 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2e730 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2e740 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2e750 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2e760 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2e770 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2e780 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2e790 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2e7a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2e7b0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2e7c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2e7d0 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2e7e0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2e7f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2e800 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2e810 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2e820 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2e830 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2e840 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2e850 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2e860 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2e870 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2e880 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2e890 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2e8a0 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2e8b0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2e8c0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2e8d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2e8e0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
2e8f0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2e900 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e  P) and sqlite3_n
2e910 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29  ormalized_sql(P)
2e920 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20  .** are managed 
2e930 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72  by SQLite and ar
2e940 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2e950 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2e960 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2e970 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2e980 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2e990 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2e9a0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2e9b0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2e9c0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2e9d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2e9e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2e9f0 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2ea00 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2ea10 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2ea20 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2ea30 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2ea40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ea50 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2ea60 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2ea70 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2ea80 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2ea90 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e  tmt *pStmt);.con
2eaa0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2eab0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2eac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ead0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2eae0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2eaf0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2eb00 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2eb10 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2eb20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2eb30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2eb40 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2eb50 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2eb60 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2eb70 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2eb80 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2eb90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eba0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2ebb0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2ebc0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2ebd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2ebe0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2ebf0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2ec00 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2ec10 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2ec20 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2ec30 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2ec40 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2ec50 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2ec60 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2ec70 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2ec80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ec90 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2eca0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2ecb0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2ecc0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2ecd0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2ece0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2ecf0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2ed00 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2ed10 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2ed20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2ed30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2ed40 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2ed50 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2ed60 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2ed70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2ed80 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2ed90 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2eda0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2edb0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2edc0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2edd0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2ede0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2edf0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2ee00 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2ee10 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2ee20 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2ee30 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2ee40 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2ee50 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2ee60 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2ee70 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2ee80 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2ee90 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2eea0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2eeb0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2eec0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2eed0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2eee0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2eef0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2ef00 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2ef10 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2ef20 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2ef30 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2ef40 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2ef50 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2ef60 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2ef70 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2ef80 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2ef90 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2efa0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2efb0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2efc0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2efd0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2efe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2eff0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2f000 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2f010 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2f020 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2f030 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2f040 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2f050 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2f060 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2f070 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2f080 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2f090 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2f0a0 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2f0b0 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2f0c0 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2f0d0 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2f0e0 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2f0f0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2f100 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2f110 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2f120 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2f130 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2f140 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2f150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2f160 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2f170 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f190 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2f1a0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f1b0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2f1c0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f1d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f1e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2f1f0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2f200 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2f210 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2f220 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f230 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2f240 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2f250 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2f260 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2f270 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2f280 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2f290 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2f2a0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2f2b0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2f2c0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2f2d0 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2f2e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2f2f0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2f300 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2f310 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2f320 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2f330 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2f340 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2f350 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2f360 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2f370 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2f380 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2f390 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f3a0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2f3b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2f3c0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2f3d0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2f3e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2f3f0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2f400 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2f410 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2f420 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2f430 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2f440 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2f450 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2f460 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2f470 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2f480 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2f490 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2f4a0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2f4b0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2f4c0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2f4d0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2f4e0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2f4f0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2f500 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2f510 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2f520 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2f530 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2f540 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2f550 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2f560 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2f570 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2f580 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2f590 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2f5a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f5b0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2f5c0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2f5d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f5e0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2f5f0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2f600 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2f610 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2f620 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2f630 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2f640 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2f650 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2f660 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2f670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f680 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2f690 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2f6a0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2f6b0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2f6c0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2f6d0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2f6e0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2f6f0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2f700 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2f710 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2f720 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2f730 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2f740 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2f750 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2f760 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2f770 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2f780 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2f790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2f7a0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2f7b0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2f7c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2f7d0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2f7e0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2f7f0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2f800 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2f810 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2f820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2f830 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2f840 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2f850 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2f860 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2f870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2f880 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2f890 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2f8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2f8b0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2f8c0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2f8d0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2f8e0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2f8f0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2f900 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2f910 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2f920 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2f930 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2f940 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2f950 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2f960 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2f970 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2f980 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2f990 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2f9a0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2f9b0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2f9c0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2f9d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2f9e0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2f9f0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2fa00 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2fa10 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2fa20 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2fa30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2fa40 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2fa50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2fa60 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2fa70 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2fa80 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2fa90 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2faa0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2fab0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2fac0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2fad0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2fae0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2faf0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2fb00 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2fb10 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2fb20 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2fb30 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2fb40 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2fb50 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2fb60 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2fb70 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2fb80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fb90 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2fba0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2fbb0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2fbc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2fbd0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2fbe0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2fbf0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2fc00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fc10 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2fc20 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2fc30 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2fc40 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2fc50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fc60 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2fc70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2fc80 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2fc90 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2fca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fcb0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2fcc0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2fcd0 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2fce0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2fcf0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2fd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2fd10 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2fd20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2fd30 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2fd40 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2fd50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2fd60 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2fd70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2fd80 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2fd90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2fda0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2fdb0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2fdc0 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2fdd0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2fde0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2fdf0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2fe00 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2fe10 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2fe20 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2fe30 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2fe40 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2fe50 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2fe60 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2fe70 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2fe80 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2fe90 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2fea0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2feb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fec0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2fed0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2fee0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2fef0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2ff00 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2ff10 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2ff20 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2ff30 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ff40 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2ff50 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2ff60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2ff70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2ff80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2ff90 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2ffa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2ffb0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2ffc0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ffd0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2ffe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2fff0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
30000 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30010 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
30020 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
30030 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
30040 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
30050 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30060 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
30070 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
30080 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
30090 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
300a0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
300b0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
300c0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
300d0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
300e0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
300f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30100 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
30110 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
30120 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
30130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30140 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
30150 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
30160 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
30170 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
30180 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
30190 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
301a0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
301b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
301c0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
301d0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
301e0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
301f0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
30200 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
30210 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
30220 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
30230 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
30240 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
30250 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
30260 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
30270 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
30280 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
30290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
302a0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
302b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
302c0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
302d0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
302e0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
302f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
30300 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
30310 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
30320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30330 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
30340 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
30350 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
30360 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
30370 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
30380 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
30390 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
303a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
303b0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
303c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
303d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
303e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
303f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
30400 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
30410 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
30420 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
30430 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
30440 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
30450 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
30460 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
30470 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
30480 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
30490 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
304a0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
304b0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
304c0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
304d0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
304e0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
304f0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
30500 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
30510 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30520 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
30530 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
30540 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
30550 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
30560 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
30570 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
30580 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
30590 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
305a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
305b0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
305c0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
305d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
305e0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
305f0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
30600 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
30610 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
30620 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
30630 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
30640 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30650 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
30660 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
30670 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
30680 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30690 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
306a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
306b0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
306c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
306d0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
306e0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
306f0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
30700 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
30710 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
30720 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
30730 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
30740 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
30750 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
30760 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
30770 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
30780 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
30790 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
307a0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
307b0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
307c0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
307d0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
307e0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
307f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
30800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30810 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
30820 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
30830 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
30840 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
30850 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
30860 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
30870 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
30880 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
30890 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
308a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
308b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
308c0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
308d0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
308e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
308f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
30900 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
30910 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
30920 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
30930 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30940 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
30950 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
30960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30970 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
30980 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
30990 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
309a0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
309b0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
309c0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
309d0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
309e0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
309f0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
30a00 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
30a10 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
30a20 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
30a30 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
30a40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
30a50 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
30a60 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
30a70 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
30a80 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
30a90 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
30aa0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
30ab0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
30ac0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
30ad0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
30ae0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30af0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
30b00 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
30b10 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
30b20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
30b30 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
30b40 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
30b50 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
30b60 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
30b70 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
30b80 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
30b90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
30ba0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
30bb0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
30bc0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
30bd0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
30be0 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
30bf0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
30c00 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
30c10 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
30c20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
30c30 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
30c40 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
30c50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
30c60 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
30c70 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
30c80 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30c90 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
30ca0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
30cb0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
30cc0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
30cd0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
30ce0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
30cf0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
30d00 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
30d10 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
30d20 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
30d30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
30d40 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
30d50 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
30d60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
30d70 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
30d80 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
30d90 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
30da0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
30db0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
30dc0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
30dd0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
30de0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
30df0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
30e00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
30e10 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
30e20 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
30e30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
30e40 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
30e50 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
30e60 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
30e70 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
30e80 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
30e90 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
30ea0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
30eb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
30ec0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
30ed0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30ee0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
30ef0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
30f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
30f10 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
30f20 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
30f30 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
30f40 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
30f50 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
30f60 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
30f70 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
30f80 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
30f90 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
30fa0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
30fb0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
30fc0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
30fd0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
30fe0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
30ff0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
31000 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
31010 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
31020 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
31030 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
31040 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
31050 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
31060 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
31070 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
31080 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
31090 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
310a0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
310b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
310c0 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
310d0 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
310e0 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
310f0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
31100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31110 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
31120 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
31130 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
31140 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31150 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
31160 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
31170 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
31180 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
31190 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
311a0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
311b0 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
311c0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
311d0 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
311e0 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
311f0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
31200 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
31210 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
31220 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
31230 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
31240 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
31250 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
31260 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
31270 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
31280 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
31290 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
312a0 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
312b0 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
312c0 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
312d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
312e0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
312f0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
31300 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
31310 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
31320 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
31330 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
31340 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
31350 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
31360 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
31370 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
31380 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
31390 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
313a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
313b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
313c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
313d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
313e0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
313f0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
31400 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
31410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31420 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
31430 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
31440 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
31450 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
31460 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
31470 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
31480 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
31490 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
314a0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
314b0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
314c0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
314d0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
314e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
314f0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
31500 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
31510 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
31520 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
31530 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
31540 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
31550 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
31560 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
31570 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
31580 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
31590 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
315a0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
315b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
315c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
315d0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
315e0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
315f0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
31600 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
31610 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
31620 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
31630 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
31640 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
31650 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
31660 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
31670 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31680 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31690 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
316a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
316b0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
316c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
316d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
316e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
316f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31710 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
31720 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
31730 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
31740 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
31750 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
31760 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
31770 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
31780 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
31790 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
317a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
317b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
317c0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
317d0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
317e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
317f0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
31800 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
31810 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
31820 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
31830 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
31840 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
31850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
31860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31870 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
31880 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
31890 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
318a0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
318b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
318c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
318d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
318e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
318f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
31900 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
31910 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
31920 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
31930 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
31940 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
31950 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
31960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31970 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
31980 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
31990 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
319a0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
319b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
319c0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
319d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
319e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
319f0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
31a00 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
31a10 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
31a20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
31a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
31a40 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
31a50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
31a60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
31a70 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
31a80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31a90 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
31aa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31ab0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
31ac0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
31ad0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31ae0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
31af0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
31b00 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
31b10 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
31b20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
31b30 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
31b40 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
31b50 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
31b60 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
31b70 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
31b80 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
31b90 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
31ba0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
31bb0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
31bc0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
31bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
31be0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
31bf0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
31c00 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
31c10 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
31c20 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
31c30 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
31c40 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
31c50 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
31c60 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
31c70 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
31c80 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
31c90 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
31ca0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
31cb0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
31cc0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
31cd0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
31ce0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
31cf0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
31d00 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
31d10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
31d20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
31d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
31d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31d50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
31d60 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
31d70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31d80 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
31d90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
31da0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
31db0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
31dc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31dd0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
31de0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
31df0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31e00 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
31e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31e20 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
31e30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31e40 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
31e50 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
31e60 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
31e70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31e80 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
31e90 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
31ea0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
31eb0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
31ec0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
31ed0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
31ee0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
31ef0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
31f00 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
31f10 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
31f20 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
31f30 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
31f40 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
31f50 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
31f60 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
31f70 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
31f80 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
31f90 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
31fa0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
31fb0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
31fc0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
31fd0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
31fe0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
31ff0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
32000 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
32010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
32020 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
32030 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
32040 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
32050 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
32060 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
32070 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
32080 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
32090 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
320a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
320b0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
320c0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
320d0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
320e0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
320f0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
32100 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
32110 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
32120 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
32130 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
32140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32150 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
32160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32170 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
32180 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32190 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
321a0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
321b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
321c0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
321d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
321e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
321f0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
32200 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32210 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32220 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
32230 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
32240 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
32250 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
32260 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
32270 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
32280 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32290 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
322a0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
322b0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
322c0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
322d0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
322e0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
322f0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
32300 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
32310 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
32320 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
32330 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
32340 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
32350 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
32360 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
32370 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
32380 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
32390 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
323a0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
323b0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
323c0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
323d0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
323e0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
323f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32400 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
32410 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32420 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
32430 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
32440 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
32450 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
32460 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32470 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
32480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
32490 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
324a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
324b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
324c0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
324d0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
324e0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
324f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
32500 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
32510 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
32520 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
32530 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32540 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
32550 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
32560 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
32570 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
32580 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
32590 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
325a0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
325b0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
325c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
325d0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
325e0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
325f0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
32600 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
32610 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
32620 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
32630 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32640 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
32650 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
32660 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
32670 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32680 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
32690 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
326a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
326b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
326c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
326d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
326e0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
326f0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
32700 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
32710 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32720 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
32730 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
32740 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
32750 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
32760 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
32770 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
32780 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
32790 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
327a0 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
327b0 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
327c0 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
327d0 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
327e0 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
327f0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
32800 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
32810 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
32820 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
32830 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
32840 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
32850 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
32860 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
32870 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
32880 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32890 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
328a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
328b0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
328c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
328d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
328e0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
328f0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
32900 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
32910 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32920 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32930 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
32940 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
32950 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
32960 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
32970 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
32980 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
32990 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
329a0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
329b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
329c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
329d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
329e0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
329f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32a00 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
32a10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
32a20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
32a30 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
32a40 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
32a50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32a60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32a70 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
32a80 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
32a90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
32aa0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
32ab0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
32ac0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
32ad0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
32ae0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
32af0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
32b00 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
32b10 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
32b20 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
32b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32b40 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
32b50 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
32b60 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
32b70 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
32b80 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
32b90 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
32ba0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
32bb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
32bc0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
32bd0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
32be0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
32bf0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
32c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
32c10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
32c20 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
32c30 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
32c40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
32c50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
32c60 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
32c70 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
32c80 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
32c90 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
32ca0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
32cb0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
32cc0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
32cd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32ce0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
32cf0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
32d00 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
32d10 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
32d20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
32d30 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
32d40 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
32d50 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
32d60 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
32d70 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
32d80 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
32d90 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
32da0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
32db0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
32dc0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
32dd0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
32de0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32df0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
32e00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32e10 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
32e20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32e30 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
32e40 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
32e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32e60 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
32e70 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
32e80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32e90 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32ea0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
32eb0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
32ec0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
32ed0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32ee0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
32ef0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
32f00 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
32f10 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
32f20 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
32f30 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
32f40 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
32f50 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
32f60 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
32f70 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
32f80 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
32f90 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
32fa0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
32fb0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
32fc0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
32fd0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
32fe0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
32ff0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
33000 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
33010 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
33020 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
33030 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
33040 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
33050 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
33060 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
33070 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
33080 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
33090 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
330a0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
330b0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
330c0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
330d0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
330e0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
330f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33100 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
33110 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
33120 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
33130 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
33140 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
33150 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
33160 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
33170 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
33180 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
33190 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
331a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
331b0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
331c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
331d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
331e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
331f0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
33200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33210 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
33220 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
33230 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
33240 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
33250 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
33260 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
33270 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
33280 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
33290 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
332a0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
332b0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
332c0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
332d0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
332e0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
332f0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
33300 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
33310 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
33320 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
33330 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
33340 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
33350 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
33360 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
33370 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
33380 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
33390 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
333a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
333b0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
333c0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
333d0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
333e0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
333f0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
33400 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
33410 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
33420 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
33430 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
33440 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
33450 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
33460 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
33470 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
33480 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
33490 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
334a0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
334b0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
334c0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
334d0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
334e0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
334f0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
33500 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
33510 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
33520 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
33530 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
33540 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
33550 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
33560 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
33570 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
33580 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33590 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
335a0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
335b0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
335c0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
335d0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
335e0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
335f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
33600 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
33610 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
33620 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
33630 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
33640 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
33650 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
33660 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
33670 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
33680 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
33690 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
336a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
336b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
336c0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
336d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
336e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
336f0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
33700 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
33710 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33720 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
33730 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
33740 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
33750 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
33760 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
33770 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
33780 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
33790 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
337a0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
337b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
337c0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
337d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
337e0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
337f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
33800 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33810 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
33820 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
33830 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
33840 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
33850 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
33860 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
33870 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33880 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
33890 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
338a0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
338b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
338c0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
338d0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
338e0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
338f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
33900 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
33910 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
33920 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
33930 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
33940 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
33950 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
33960 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
33970 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
33980 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
33990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
339a0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
339b0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
339c0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
339d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
339e0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
339f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
33a00 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
33a10 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
33a20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
33a30 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
33a40 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
33a50 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
33a60 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
33a70 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
33a80 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
33a90 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
33aa0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
33ab0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
33ac0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
33ad0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
33ae0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
33af0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
33b00 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
33b10 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
33b20 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
33b30 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
33b40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
33b50 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
33b60 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
33b70 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
33b80 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
33b90 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
33ba0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
33bb0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
33bc0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
33bd0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
33be0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
33bf0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
33c00 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
33c10 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
33c20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
33c30 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
33c40 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
33c50 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
33c60 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
33c70 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
33c80 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
33c90 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
33ca0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
33cb0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
33cc0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
33cd0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
33ce0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
33cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
33d00 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
33d10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
33d20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33d30 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
33d40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
33d50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33d60 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
33d70 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
33d80 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33d90 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
33da0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
33db0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
33dc0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
33dd0 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
33de0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33df0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
33e00 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
33e10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33e20 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
33e30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33e40 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
33e50 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
33e60 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
33e70 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
33e80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33e90 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
33ea0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
33eb0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
33ec0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
33ed0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
33ee0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
33ef0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
33f00 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
33f10 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
33f20 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
33f30 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
33f40 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
33f50 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
33f60 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
33f70 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
33f80 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
33f90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33fa0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
33fb0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
33fc0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
33fd0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
33fe0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
33ff0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
34000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34010 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34020 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
34030 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
34040 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
34050 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
34060 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
34070 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
34080 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
34090 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
340a0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
340b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
340c0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
340d0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
340e0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
340f0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
34100 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
34110 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
34120 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
34130 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
34140 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
34150 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
34160 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
34170 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
34180 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
34190 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
341a0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
341b0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
341c0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
341d0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
341e0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
341f0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
34200 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
34210 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
34220 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
34230 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
34240 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
34250 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
34260 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
34270 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
34280 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
34290 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
342a0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
342b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
342c0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
342d0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
342e0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
342f0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
34300 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
34310 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
34320 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
34330 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
34340 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
34350 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
34360 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
34370 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
34380 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
34390 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
343a0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
343b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
343c0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
343d0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
343e0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
343f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34400 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
34410 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
34420 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
34430 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
34440 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
34450 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
34460 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
34470 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
34480 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
34490 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
344a0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
344b0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
344c0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
344d0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
344e0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
344f0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
34500 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
34510 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
34520 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
34530 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
34540 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
34550 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
34560 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
34570 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
34580 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
34590 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
345a0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
345b0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
345c0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
345d0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
345e0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
345f0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
34600 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
34610 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
34620 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
34630 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
34640 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
34650 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
34660 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
34670 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
34680 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
34690 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
346a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
346b0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
346c0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
346d0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
346e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
346f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
34700 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34710 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
34720 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
34730 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
34740 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
34750 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
34760 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
34770 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
34780 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
34790 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
347a0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
347b0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
347c0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
347d0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
347e0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
347f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34800 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
34810 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
34820 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
34830 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
34840 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
34850 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
34860 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
34870 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
34880 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
34890 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
348a0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
348b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
348c0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
348d0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
348e0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
348f0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
34900 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
34910 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
34920 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
34930 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
34940 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
34950 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34960 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
34970 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
34980 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
34990 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
349a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
349b0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
349c0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
349d0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
349e0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
349f0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
34a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34a10 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
34a20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
34a30 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
34a40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
34a50 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
34a60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
34a70 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
34a80 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
34a90 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
34aa0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
34ab0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
34ac0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
34ad0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
34ae0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
34af0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
34b00 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
34b10 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
34b20 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
34b30 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
34b40 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
34b50 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
34b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
34b70 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
34b80 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
34b90 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
34ba0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
34bb0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
34bc0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
34bd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
34be0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
34bf0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
34c00 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
34c10 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
34c20 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
34c30 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
34c40 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
34c50 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
34c60 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
34c70 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
34c80 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
34c90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
34ca0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
34cb0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
34cc0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
34cd0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
34ce0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
34cf0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
34d00 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
34d10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
34d20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
34d30 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
34d40 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
34d50 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
34d60 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
34d70 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
34d80 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
34d90 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
34da0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
34db0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
34dc0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
34dd0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
34de0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
34df0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
34e00 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
34e10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
34e20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
34e30 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
34e40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
34e50 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
34e60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
34e70 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
34e80 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
34e90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34ea0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34eb0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
34ec0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
34ed0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
34ee0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
34ef0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
34f00 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
34f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
34f20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
34f30 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
34f40 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
34f50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
34f60 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
34f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34f80 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
34f90 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
34fa0 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
34fb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
34fc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34fd0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
34fe0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34ff0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
35000 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
35010 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
35020 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
35030 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
35040 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
35050 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35060 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
35070 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
35080 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
35090 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
350a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
350b0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
350c0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
350d0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
350e0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
350f0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
35100 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
35110 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
35120 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
35130 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
35140 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35160 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
35170 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
35180 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
35190 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
351a0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
351b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
351c0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
351d0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
351e0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
351f0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
35200 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
35210 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
35220 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
35230 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
35240 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
35250 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
35260 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
35270 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
35280 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
35290 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
352a0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
352b0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
352c0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
352d0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
352e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
352f0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
35300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
35310 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
35320 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
35330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35340 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
35350 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
35360 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
35370 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
35380 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
35390 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
353a0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
353b0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
353c0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
353d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
353e0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
353f0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
35400 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
35410 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
35420 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
35430 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
35440 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
35450 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
35460 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
35470 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
35480 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
35490 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
354a0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
354b0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
354c0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
354d0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
354e0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
354f0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
35500 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
35510 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
35520 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
35530 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
35540 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
35550 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
35560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35570 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
35580 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
35590 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
355a0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
355b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
355c0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
355d0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
355e0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
355f0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
35600 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
35610 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
35620 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
35630 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
35640 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
35650 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
35660 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
35670 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
35680 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
35690 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
356a0 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
356b0 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
356c0 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
356d0 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
356e0 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
356f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35710 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
35720 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
35730 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
35750 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
35760 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
35770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35790 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
357a0 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
357b0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
357c0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
357d0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
357e0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
357f0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
35800 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
35810 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
35820 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
35830 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
35840 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
35850 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35860 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
35870 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
35880 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
35890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
358a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
358b0 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
358c0 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
358d0 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
358e0 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
358f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35900 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
35910 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
35920 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
35930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35950 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
35960 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
35970 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
35980 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
35990 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
359a0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
359b0 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
359c0 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
359d0 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
359e0 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
359f0 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
35a00 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
35a10 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
35a20 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
35a30 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
35a40 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
35a50 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
35a60 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
35a70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
35a80 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
35a90 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
35aa0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
35ab0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
35ac0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
35ad0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
35ae0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
35af0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
35b00 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
35b10 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
35b20 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
35b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35b40 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
35b50 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
35b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
35b70 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
35b80 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
35b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35ba0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
35bb0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
35bc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
35bd0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
35be0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
35bf0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
35c00 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
35c10 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
35c20 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
35c30 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
35c40 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
35c50 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
35c60 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
35c70 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
35c80 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
35c90 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
35ca0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
35cb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
35cc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
35cd0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
35ce0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
35cf0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
35d00 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
35d10 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
35d20 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
35d30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
35d40 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
35d50 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
35d60 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
35d70 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
35d80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
35d90 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
35da0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
35db0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
35dc0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
35dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35de0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
35df0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
35e00 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
35e10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
35e20 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
35e30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35e40 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
35e50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
35e60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
35e70 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
35e80 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
35e90 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
35ea0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
35eb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
35ec0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
35ed0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
35ee0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35ef0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
35f00 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
35f10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
35f20 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
35f30 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
35f40 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
35f50 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
35f60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35f70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
35f80 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
35f90 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
35fa0 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
35fb0 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
35fc0 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
35fd0 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
35fe0 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
35ff0 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
36000 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
36010 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
36020 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
36030 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
36040 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
36050 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
36060 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
36070 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
36080 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
36090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
360a0 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
360b0 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
360c0 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
360d0 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
360e0 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
360f0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
36100 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36110 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
36120 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
36130 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
36140 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
36150 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
36160 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
36170 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
36180 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
36190 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
361a0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
361b0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
361c0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
361d0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
361e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
361f0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
36200 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
36210 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
36220 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
36230 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
36240 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
36250 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
36260 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
36270 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
36280 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
36290 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
362a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
362b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
362c0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
362d0 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
362e0 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
362f0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
36300 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
36310 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
36320 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
36330 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
36340 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
36350 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
36360 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
36370 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
36380 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
36390 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
363a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
363b0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
363c0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
363d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
363e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
363f0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
36400 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
36410 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
36420 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
36430 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
36440 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
36450 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
36460 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
36470 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
36480 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
36490 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
364a0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
364b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
364c0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
364d0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
364e0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
364f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36500 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
36510 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
36520 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
36530 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
36540 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
36550 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
36560 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
36570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36580 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
36590 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
365a0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
365b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
365c0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
365d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
365e0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
365f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
36600 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
36610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
36620 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
36630 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
36640 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
36650 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
36660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
36670 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
36680 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
36690 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
366a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
366b0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
366c0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
366d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
366e0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
366f0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
36700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36710 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
36720 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
36730 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36740 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
36750 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
36760 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
36770 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
36780 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
36790 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
367a0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
367b0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
367c0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
367d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
367e0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
367f0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
36800 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
36810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36820 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
36830 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
36840 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
36850 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
36860 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
36870 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
36880 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
36890 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
368a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
368b0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
368c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
368d0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
368e0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
368f0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
36900 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
36910 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
36920 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
36930 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
36940 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
36950 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
36960 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
36970 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
36980 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
36990 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
369a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
369b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
369c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
369d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
369e0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
369f0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
36a00 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
36a10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
36a20 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
36a30 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
36a40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36a50 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
36a60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36a70 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
36a80 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
36a90 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
36aa0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
36ab0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
36ac0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
36ad0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
36ae0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
36af0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
36b00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
36b10 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
36b20 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
36b30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
36b40 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
36b50 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
36b60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36b70 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
36b80 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
36b90 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
36ba0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
36bb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
36bc0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
36bd0 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
36be0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
36bf0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
36c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36c10 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
36c20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36c30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36c40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
36c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
36c60 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
36c70 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
36c80 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
36c90 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
36ca0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36cb0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
36cc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36cd0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
36ce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36cf0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
36d00 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
36d10 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
36d20 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
36d30 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
36d40 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
36d50 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
36d60 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
36d70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
36d80 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
36d90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36da0 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
36db0 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
36dc0 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
36dd0 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
36de0 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
36df0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
36e00 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
36e10 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
36e20 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
36e30 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
36e40 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
36e50 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
36e60 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
36e70 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
36e80 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
36e90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
36ea0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
36eb0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
36ec0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
36ed0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
36ee0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
36ef0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
36f00 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
36f10 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
36f20 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
36f30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
36f40 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
36f50 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
36f60 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
36f70 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
36f80 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
36f90 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
36fa0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
36fb0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
36fc0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
36fd0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
36fe0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
36ff0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
37000 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
37010 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
37020 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
37030 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
37040 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
37050 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
37060 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
37070 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
37080 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
37090 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
370a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
370b0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
370c0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
370d0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
370e0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
370f0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
37100 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
37110 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
37120 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
37130 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
37140 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
37150 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
37160 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
37170 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
37180 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
37190 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
371a0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
371b0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
371c0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
371d0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
371e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
371f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
37200 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
37210 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
37220 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
37230 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
37240 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
37250 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
37260 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
37270 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
37280 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
37290 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
372a0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
372b0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
372c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
372d0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
372e0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
372f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
37300 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
37310 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
37320 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
37330 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
37340 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
37350 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
37360 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
37370 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
37380 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
37390 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
373a0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
373b0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
373c0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
373d0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
373e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
373f0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
37400 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
37410 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
37420 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37430 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
37440 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
37450 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
37460 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
37470 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
37480 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
37490 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
374a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
374b0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
374c0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
374d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
374e0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
374f0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
37500 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
37510 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
37520 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
37530 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
37540 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
37550 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
37560 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
37570 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
37580 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
37590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
375a0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
375b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
375c0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
375d0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
375e0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
375f0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
37600 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
37610 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
37620 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
37630 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
37640 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
37650 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
37660 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
37670 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
37680 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
37690 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
376a0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
376b0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
376c0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
376d0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
376e0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
376f0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
37700 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
37710 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
37720 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
37730 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
37740 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
37750 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
37760 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
37770 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
37780 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
37790 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
377a0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
377b0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
377c0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
377d0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
377e0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
377f0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
37800 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
37810 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
37820 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
37830 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
37840 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
37850 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
37860 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
37870 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
37880 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
37890 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
378a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
378b0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
378c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
378d0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
378e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
378f0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
37900 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
37910 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
37920 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
37930 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
37940 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
37950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37960 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
37970 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
37980 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
37990 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
379a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
379b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
379c0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
379d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
379e0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
379f0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
37a00 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
37a10 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
37a20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
37a30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
37a40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
37a50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
37a60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
37a70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
37a80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
37a90 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
37aa0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
37ab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
37ac0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
37ad0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
37ae0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
37af0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
37b00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
37b10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
37b20 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
37b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37b40 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
37b50 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
37b60 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
37b70 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
37b80 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
37b90 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
37ba0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
37bb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
37bc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
37bd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
37be0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
37bf0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
37c00 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
37c10 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
37c20 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
37c30 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
37c40 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
37c50 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
37c60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
37c70 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
37c80 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
37c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37ca0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
37cb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
37cc0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  ]..**.** As long
37cd0 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 70 61   as the input pa
37ce0 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 6f 72  rameters are cor
37cf0 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f 75 74  rect, these rout
37d00 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a  ines will only.*
37d10 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f 75 74  * fail if an out
37d20 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72  -of-memory error
37d30 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
37d40 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73 69   format conversi
37d50 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20  on..** Only the 
37d60 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65 74  following subset
37d70 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 61   of interfaces a
37d80 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 6f 75  re subject to ou
37d90 74 2d 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65  t-of-memory.** e
37da0 72 72 6f 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rrors:.**.** <ul
37db0 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
37dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a  3_column_blob().
37dd0 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
37de0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a  column_text().**
37df0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
37e00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
37e10 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
37e20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
37e30 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
37e40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
37e50 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ul>.**.** If 
37e60 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  an out-of-memory
37e70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 74   error occurs, t
37e80 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
37e90 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 73 65 0a  alue from these.
37ea0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 69 73 20 74  ** routines is t
37eb0 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 68  he same as if th
37ec0 65 20 63 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e  e column had con
37ed0 74 61 69 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55  tained an SQL NU
37ee0 4c 4c 20 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c  LL value..** Val
37ef0 69 64 20 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75  id SQL NULL retu
37f00 72 6e 73 20 63 61 6e 20 62 65 20 64 69 73 74 69  rns can be disti
37f10 6e 67 75 69 73 68 65 64 20 66 72 6f 6d 20 6f 75  nguished from ou
37f20 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
37f30 72 73 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e  rs.** by invokin
37f40 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  g the [sqlite3_e
37f50 72 72 63 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69  rrcode()] immedi
37f60 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65 20  ately after the 
37f70 73 75 73 70 65 63 74 0a 2a 2a 20 72 65 74 75 72  suspect.** retur
37f80 6e 20 76 61 6c 75 65 20 69 73 20 6f 62 74 61 69  n value is obtai
37f90 6e 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ned and before a
37fa0 6e 79 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ny.** other SQLi
37fb0 74 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  te interface is 
37fc0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 73 61  called on the sa
37fd0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37fe0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e  nection]..*/.con
37ff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
38000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
38010 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
38020 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
38030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
38040 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
38050 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
38060 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
38070 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
38080 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
38090 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
380a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
380b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
380c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
380d0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
380e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
380f0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
38100 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
38110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
38120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
38130 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
38140 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
38150 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
38160 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
38170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
38180 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
38190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
381a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
381b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
381c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
381d0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
381e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
381f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
38200 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
38210 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
38220 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38230 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
38240 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
38250 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
38260 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
38270 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
38280 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
38290 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
382a0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
382b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
382c0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
382d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
382e0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
382f0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
38300 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
38310 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
38320 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
38330 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
38340 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
38350 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
38360 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
38370 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
38380 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
38390 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
383a0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
383b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
383c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
383d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
383e0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
383f0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
38400 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
38410 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
38420 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
38430 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
38440 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
38450 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
38460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38470 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
38480 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
38490 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
384a0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
384b0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
384c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
384d0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
384e0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
384f0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
38500 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
38510 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
38520 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
38530 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
38540 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
38550 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
38560 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
38570 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
38580 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
38590 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
385a0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
385b0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
385c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
385d0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
385e0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
385f0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
38600 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
38610 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
38620 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
38630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38640 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
38650 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
38660 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
38670 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
38680 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
38690 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
386a0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
386b0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
386c0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
386d0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
386e0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
386f0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
38700 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
38710 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
38720 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
38730 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
38740 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
38750 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
38760 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
38770 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
38780 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
38790 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c