/ Hex Artifact Content
Login

Artifact 25586d23b612610f2123dc3390c764f8c0caa69ba0975bb9f67dbb860f0b53a7:


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 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
1ad60 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 64  ivates the.** "d
1ad70 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 66  efensive" flag f
1ad80 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
1ad90 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20  nnection.  When 
1ada0 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a 2a  the defensive.**
1adb0 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 64   flag is enabled
1adc0 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 75  , language featu
1add0 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 6f  res that allow o
1ade0 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 0a  rdinary SQL to .
1adf0 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20  ** deliberately 
1ae00 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 61  corrupt the data
1ae10 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 69  base file are di
1ae20 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 73  sabled.  The dis
1ae30 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 65  abled.** feature
1ae40 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 72  s include but ar
1ae50 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 6f  e not limited to
1ae60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
1ae70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1ae80 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 74  The [PRAGMA writ
1ae90 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20  able_schema=ON] 
1aea0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c  statement..** <l
1aeb0 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68 65  i> Writes to the
1aec0 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65 5d   [sqlite_dbpage]
1aed0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
1aee0 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20 77  ** <li> Direct w
1aef0 72 69 74 65 73 20 74 6f 20 73 68 61 64 6f 77 20  rites to shadow 
1af00 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e  tables..** </ul>
1af10 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  .** </dd>.** </d
1af20 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1af30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1af40 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
1af50 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
1af60 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
1af70 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1af80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
1af90 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
1afa0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
1afb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1afc0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1afd0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
1afe0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
1aff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b000 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1b010 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
1b020 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
1b030 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b040 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1b050 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
1b060 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
1b070 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b080 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b090 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
1b0a0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
1b0b0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b0c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b0d0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
1b0e0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
1b0f0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b100 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b110 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
1b120 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f            1007 /
1b130 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b150 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1b160 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38  P           1008
1b170 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b190 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1b1a0 54 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30  TABASE        10
1b1b0 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  09 /* int int* *
1b1c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b1d0 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53  _DBCONFIG_DEFENS
1b1e0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IVE             
1b1f0 31 30 31 30 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1010 /* int int*
1b200 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b210 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20  TE_DBCONFIG_MAX 
1b220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b230 20 20 31 30 31 30 20 2f 2a 20 4c 61 72 67 65 73    1010 /* Larges
1b240 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f  t DBCONFIG */../
1b250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1b260 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
1b270 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
1b280 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
1b290 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b2a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1b2b0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1b2c0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
1b2d0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
1b2e0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
1b2f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
1b300 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
1b310 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
1b320 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
1b330 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
1b340 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
1b350 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
1b360 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
1b370 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
1b380 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
1b390 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
1b3a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b3b0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
1b3c0 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
1b3d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
1b3e0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
1b3f0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
1b400 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
1b410 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
1b420 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
1b430 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
1b440 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
1b450 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
1b460 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
1b470 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
1b480 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
1b490 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
1b4a0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
1b4b0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
1b4c0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
1b4d0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
1b4e0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
1b4f0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
1b500 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
1b510 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
1b520 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
1b530 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
1b540 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
1b550 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
1b560 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
1b570 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
1b580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b590 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1b5a0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
1b5b0 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75  ace usually retu
1b5c0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
1b5d0 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  of.** the most r
1b5e0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
1b5f0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
1b600 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
1b610 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
1b620 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
1b630 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e  onnection D. ^In
1b640 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
1b650 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
1b660 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63  s are not.** rec
1b670 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75  orded. ^If no su
1b680 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1b690 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
1b6a0 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f  bles have ever o
1b6b0 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74  ccurred .** on t
1b6c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b6d0 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73  ection D, then s
1b6e0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1b6f0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
1b700 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a  rns .** zero..**
1b710 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62  .** As well as b
1b720 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74  eing set automat
1b730 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61  ically as rows a
1b740 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
1b750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
1b760 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  les, the value r
1b770 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
1b780 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
1b790 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62  set explicitly b
1b7a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  y.** [sqlite3_se
1b7b0 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1b7c0 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d  wid()].**.** Som
1b7d0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
1b7e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
1b7f0 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20  may INSERT rows 
1b800 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1b810 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  s as.** part of 
1b820 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61  committing a tra
1b830 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74  nsaction (e.g. t
1b840 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63  o flush data acc
1b850 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f  umulated in memo
1b860 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20  ry.** to disk). 
1b870 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62  In this case sub
1b880 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1b890 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
1b8a0 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a  eturn the rowid.
1b8b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1b8c0 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61  th these interna
1b8d0 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  l INSERT operati
1b8e0 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73  ons, which leads
1b8f0 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74   to .** unintuit
1b900 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72  ive results. Vir
1b910 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
1b920 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20  mentations that 
1b930 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69  do write to rowi
1b940 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74  d.** tables in t
1b950 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69  his way can avoi
1b960 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62  d this problem b
1b970 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20  y restoring the 
1b980 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77  original .** row
1b990 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b  id value using [
1b9a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1b9b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1b9c0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
1b9d0 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f  g .** control to
1b9e0 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a   the user..**.**
1b9f0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
1ba00 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
1ba10 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74  a trigger then t
1ba20 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
1ba30 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20   .** return the 
1ba40 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
1ba50 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c  nserted row as l
1ba60 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
1ba70 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e  er is .** runnin
1ba80 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67  g. Once the trig
1ba90 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73  ger program ends
1baa0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1bab0 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
1bac0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
1bad0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
1bae0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
1baf0 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a  er was fired.)^.
1bb00 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
1bb10 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
1bb20 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
1bb30 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
1bb40 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
1bb50 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
1bb60 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
1bb70 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1bb80 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
1bb90 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
1bba0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
1bbb0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
1bbc0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
1bbd0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
1bbe0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
1bbf0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
1bc00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1bc10 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
1bc20 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
1bc30 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
1bc40 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
1bc50 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
1bc60 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
1bc70 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
1bc80 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
1bc90 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
1bca0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
1bcb0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
1bcc0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
1bcd0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
1bce0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
1bcf0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
1bd00 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
1bd10 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
1bd20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1bd30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
1bd40 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
1bd50 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
1bd60 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
1bd70 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
1bd80 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
1bd90 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
1bda0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
1bdb0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
1bdc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
1bdd0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
1bde0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
1bdf0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
1be00 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
1be10 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
1be20 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
1be30 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
1be40 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
1be50 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
1be60 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
1be70 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
1be80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
1be90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1bea0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
1beb0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
1bec0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
1bed0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
1bee0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
1bef0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1bf00 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1bf10 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
1bf20 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
1bf30 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
1bf40 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
1bf50 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
1bf60 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
1bf70 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
1bf80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1bf90 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1bfa0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
1bfb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bfc0 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73  Set the Last Ins
1bfd0 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e  ert Rowid value.
1bfe0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1bff0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
1c000 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1c010 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52  nsert_rowid(D, R
1c020 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20  ) method allows 
1c030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1c040 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61  to.** set the va
1c050 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1c060 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
1c070 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c080 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69  d(D) to R .** wi
1c090 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20  thout inserting 
1c0a0 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64  a row into the d
1c0b0 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64  atabase..*/.void
1c0c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
1c0d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1c0e0 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f  qlite3*,sqlite3_
1c0f0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
1c100 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
1c110 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
1c120 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1c130 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c140 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1c150 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
1c160 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
1c170 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
1c180 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1c190 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
1c1a0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
1c1b0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c1c0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
1c1d0 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
1c1e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1c1f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1c200 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
1c210 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
1c220 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
1c230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
1c240 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
1c250 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1c260 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1c270 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
1c280 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
1c290 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
1c2a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1c2b0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1c2c0 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
1c2d0 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
1c2e0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
1c2f0 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
1c300 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
1c310 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
1c320 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
1c330 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
1c340 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
1c350 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1c360 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
1c370 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1c380 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
1c390 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
1c3a0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
1c3b0 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
1c3c0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
1c3d0 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
1c3e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1c3f0 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
1c400 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
1c410 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c420 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
1c430 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
1c440 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
1c450 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
1c460 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
1c470 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
1c480 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
1c490 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
1c4a0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
1c4b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c4c0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
1c4d0 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
1c4e0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1c4f0 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
1c500 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
1c510 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
1c520 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
1c530 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1c540 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
1c550 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
1c560 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
1c570 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1c580 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
1c590 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
1c5a0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1c5b0 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
1c5c0 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
1c5d0 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
1c5e0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1c5f0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
1c600 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1c610 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
1c620 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1c630 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
1c640 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
1c650 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
1c660 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
1c670 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
1c680 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
1c690 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
1c6a0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
1c6b0 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
1c6c0 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
1c6d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c6e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1c6f0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1c700 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
1c710 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
1c720 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
1c730 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
1c740 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
1c750 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
1c760 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
1c770 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
1c780 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1c790 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
1c7a0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
1c7b0 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
1c7c0 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
1c7d0 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
1c7e0 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
1c7f0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1c800 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
1c810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
1c820 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
1c830 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
1c840 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
1c850 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1c860 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1c870 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
1c880 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
1c890 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
1c8a0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
1c8b0 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
1c8c0 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
1c8d0 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
1c8e0 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
1c8f0 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
1c900 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1c910 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
1c920 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c930 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
1c940 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1c950 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1c960 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
1c970 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1c980 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1c990 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
1c9a0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  gger..**.** If a
1c9b0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1c9c0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1c9d0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1c9e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1c9f0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1ca00 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1ca10 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1ca20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1ca30 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
1ca40 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1ca50 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ngful..**.** See
1ca60 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a   also:.** <ul>.*
1ca70 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69  * <li> the [sqli
1ca80 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1ca90 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  s()] interface.*
1caa0 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e  * <li> the [coun
1cab0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1cac0 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63  ].** <li> the [c
1cad0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1cae0 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74  ction].** <li> t
1caf0 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e  he [data_version
1cb00 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c   pragma].** </ul
1cb10 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1cb20 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1cb30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cb40 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1cb50 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1cb60 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1cb70 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1cb80 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1cb90 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1cba0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1cbb0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1cbc0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1cbd0 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1cbe0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1cbf0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1cc00 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1cc10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1cc20 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1cc30 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1cc40 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1cc50 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1cc60 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1cc70 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1cc80 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1cc90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1cca0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1ccb0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1ccc0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1ccd0 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1cce0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1ccf0 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1cd00 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1cd10 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1cd20 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1cd30 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1cd40 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1cd50 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1cd60 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1cd70 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1cd80 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1cd90 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1cda0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1cdb0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1cdc0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
1cdd0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  s the [sqlite3_t
1cde0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d  otal_changes(D)]
1cdf0 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
1ce00 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62  reports the numb
1ce10 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68  er.** of rows th
1ce20 61 74 20 63 68 61 6e 67 65 64 20 64 75 65 20 74  at changed due t
1ce30 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  o SQL statement 
1ce40 72 75 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61  run against data
1ce50 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
1ce60 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67  on D.  Any chang
1ce70 65 73 20 62 79 20 6f 74 68 65 72 20 64 61 74 61  es by other data
1ce80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1ce90 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1cea0 20 54 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67   To detect chang
1ceb0 65 73 20 61 67 61 69 6e 73 74 20 61 20 64 61 74  es against a dat
1cec0 61 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20  abase file from 
1ced0 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a  other database.*
1cee0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73  * connections us
1cef0 65 20 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61  e the [PRAGMA da
1cf00 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d  ta_version] comm
1cf10 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53  and or the.** [S
1cf20 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41  QLITE_FCNTL_DATA
1cf30 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20  _VERSION] [file 
1cf40 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a  control]..** .**
1cf50 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1cf60 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1cf70 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1cf80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf90 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1cfa0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1cfb0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1cfc0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1cfd0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1cfe0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1cff0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1d000 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1d010 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
1d020 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  > the [sqlite3_c
1d030 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1d040 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ace.** <li> the 
1d050 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1d060 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74  ragma].** <li> t
1d070 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1d080 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c  L function].** <
1d090 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65  li> the [data_ve
1d0a0 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a  rsion pragma].**
1d0b0 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54   <li> the [SQLIT
1d0c0 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52  E_FCNTL_DATA_VER
1d0d0 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74  SION] [file cont
1d0e0 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  rol].** </ul>.*/
1d0f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
1d100 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
1d110 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1d120 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
1d130 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
1d140 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
1d150 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1d160 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
1d170 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
1d180 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1d190 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
1d1a0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
1d1b0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
1d1c0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
1d1d0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
1d1e0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
1d1f0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
1d200 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
1d210 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
1d220 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
1d230 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
1d240 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
1d250 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
1d260 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
1d270 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
1d280 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1d290 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
1d2a0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
1d2b0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
1d2c0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
1d2d0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
1d2e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
1d2f0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
1d300 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
1d310 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1d320 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
1d330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d340 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
1d350 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
1d360 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
1d370 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
1d380 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
1d390 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
1d3a0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
1d3b0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
1d3c0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
1d3d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1d3e0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
1d3f0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
1d400 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
1d410 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
1d420 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
1d430 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
1d440 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
1d450 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
1d460 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
1d470 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
1d480 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1d490 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
1d4a0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
1d4b0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1d4c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1d4d0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
1d4e0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
1d4f0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1d500 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
1d510 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
1d520 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
1d530 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
1d540 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
1d550 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1d560 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
1d570 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
1d580 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
1d590 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1d5a0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
1d5b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d5c0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
1d5d0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
1d5e0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1d5f0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1d600 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1d610 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
1d620 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
1d630 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1d640 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
1d650 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
1d660 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
1d670 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
1d680 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
1d690 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1d6a0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
1d6b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1d6c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1d6d0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
1d6e0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
1d6f0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1d700 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
1d710 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
1d720 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
1d730 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
1d740 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1d750 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
1d760 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
1d770 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1d780 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
1d790 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
1d7a0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
1d7b0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1d7c0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1d7d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1d7e0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
1d7f0 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  turns..*/.void s
1d800 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d810 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1d820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1d830 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1d840 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1d850 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1d860 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d870 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1d880 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1d890 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1d8a0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1d8b0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1d8c0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1d8d0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1d8e0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1d8f0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1d900 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1d910 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1d920 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1d930 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1d940 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1d950 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1d960 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1d970 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1d980 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1d990 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1d9a0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1d9b0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1d9c0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1d9d0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1d9e0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1d9f0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1da00 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1da10 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1da20 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1da30 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1da40 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1da50 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1da60 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1da70 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1da80 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1da90 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1daa0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1dab0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1dac0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1dad0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1dae0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1daf0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1db00 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1db10 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1db20 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1db30 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1db40 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1db50 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1db60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1db70 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1db80 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1db90 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1dba0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1dbb0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1dbc0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1dbd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1dbe0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1dbf0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1dc00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1dc10 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1dc20 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1dc30 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1dc40 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1dc50 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1dc60 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1dc70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1dc80 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1dc90 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1dca0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1dcb0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1dcc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1dcd0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1dce0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1dcf0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1dd00 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1dd10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1dd20 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1dd30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1dd40 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1dd50 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1dd60 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1dd70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1dd80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1dd90 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1dda0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1ddb0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1ddc0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1ddd0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1dde0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1ddf0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1de00 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1de10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1de20 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1de30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1de40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1de50 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1de60 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
1de70 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1de80 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
1de90 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1dea0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1deb0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1dec0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1ded0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1dee0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1def0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1df00 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1df10 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1df20 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1df30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1df40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1df50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1df60 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1df70 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1df80 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1df90 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1dfa0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1dfb0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1dfc0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1dfd0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1dfe0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1dff0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1e000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e010 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1e020 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1e030 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1e040 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1e050 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1e060 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1e070 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1e080 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1e090 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1e0a0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1e0b0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1e0c0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1e0d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1e0e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1e0f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1e100 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1e110 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1e120 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1e130 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1e140 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1e150 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1e160 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1e170 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1e180 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1e190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1e1a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1e1b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1e1c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1e1d0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1e1e0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1e1f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1e200 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1e210 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1e220 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1e230 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1e240 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1e250 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1e260 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1e270 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1e280 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1e290 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1e2a0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1e2b0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1e2c0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1e2d0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1e2e0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1e2f0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1e300 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1e310 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1e320 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1e330 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1e340 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1e350 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1e360 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1e370 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1e380 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1e390 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1e3a0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1e3b0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1e3c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1e3d0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1e3e0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1e3f0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1e400 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1e410 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1e420 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1e430 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1e440 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1e450 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1e460 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1e470 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1e480 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1e490 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1e4a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1e4b0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1e4c0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1e4d0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1e4e0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1e4f0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1e500 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1e510 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1e520 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1e530 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1e540 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1e550 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1e560 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1e570 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1e580 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1e590 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1e5a0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1e5b0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1e5c0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1e5d0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1e5e0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1e5f0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1e600 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1e610 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1e620 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1e630 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1e640 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1e650 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1e660 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1e670 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1e680 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1e690 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1e6a0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1e6b0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1e6c0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1e6d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1e6e0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1e6f0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1e700 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1e710 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1e720 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1e730 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1e740 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1e750 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1e760 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1e770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1e780 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1e790 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1e7a0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1e7b0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1e7c0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1e7d0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1e7e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e7f0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1e800 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1e810 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1e820 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1e830 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1e840 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1e850 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1e860 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1e870 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1e880 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1e890 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1e8a0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1e8b0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1e8c0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1e8d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1e8e0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1e8f0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1e900 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1e910 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1e920 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1e930 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1e940 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1e950 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1e960 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1e970 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1e980 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1e990 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1e9a0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1e9b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1e9c0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1e9d0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1e9e0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1e9f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ea00 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1ea10 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1ea20 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1ea30 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1ea40 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1ea50 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1ea60 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1ea70 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1ea80 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1ea90 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1eaa0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1eab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1eac0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1ead0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1eae0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1eaf0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1eb00 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1eb10 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1eb20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1eb30 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1eb40 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1eb50 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1eb60 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1eb70 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1eb80 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1eb90 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1eba0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1ebb0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1ebc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1ebd0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1ebe0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1ebf0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1ec00 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1ec10 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1ec20 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1ec30 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1ec40 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1ec50 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1ec60 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1ec70 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1ec80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1ec90 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1eca0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1ecb0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1ecc0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1ecd0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1ece0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1ecf0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1ed00 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1ed10 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1ed20 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1ed30 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ed40 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1ed50 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1ed60 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1ed70 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1ed80 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1ed90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1eda0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1edb0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1edc0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1edd0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1ede0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1edf0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1ee00 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1ee10 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1ee20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1ee30 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1ee40 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1ee50 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1ee60 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1ee70 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1ee80 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1ee90 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1eea0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1eeb0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1eec0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1eed0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1eee0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1eef0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1ef00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1ef10 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1ef20 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1ef30 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1ef40 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1ef50 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1ef60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1ef70 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1ef80 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1ef90 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1efa0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1efb0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1efc0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1efd0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1efe0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1eff0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1f000 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1f010 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1f020 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1f030 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1f040 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1f050 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1f060 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1f070 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1f080 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1f090 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1f0a0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1f0b0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1f0c0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1f0d0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1f0e0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1f0f0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1f100 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1f110 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1f120 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1f130 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1f140 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1f150 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1f160 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1f170 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1f180 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1f190 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1f1a0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1f1b0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1f1c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1f1d0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1f1e0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1f1f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1f200 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1f210 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1f220 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1f230 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1f240 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f250 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1f260 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1f270 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1f280 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1f290 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1f2a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1f2b0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1f2c0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1f2d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1f2e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1f2f0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1f300 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1f310 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1f320 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1f330 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1f340 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1f350 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1f360 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1f370 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1f380 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f390 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1f3a0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1f3b0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1f3c0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1f3d0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1f3e0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1f3f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1f400 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1f410 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1f420 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1f430 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1f440 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1f450 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1f460 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1f470 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1f480 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1f490 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1f4a0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1f4b0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1f4c0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1f4d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1f4e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f4f0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1f500 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f510 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1f520 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1f530 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1f540 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1f550 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1f560 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1f570 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1f580 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1f590 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1f5a0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1f5b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f5c0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1f5d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f5e0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1f5f0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1f600 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1f610 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f620 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1f630 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1f640 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1f650 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1f660 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1f670 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1f680 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1f690 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1f6a0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1f6b0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1f6c0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1f6d0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1f6e0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1f6f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1f700 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1f710 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1f720 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1f730 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1f740 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1f750 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1f760 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1f770 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1f780 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1f790 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1f7a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1f7b0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1f7c0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1f7d0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1f7e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1f7f0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1f800 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1f810 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1f820 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1f830 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1f840 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f850 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1f860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1f870 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1f880 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1f890 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1f8a0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1f8b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1f8c0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1f8d0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1f8e0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1f8f0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1f900 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1f910 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1f920 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1f930 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1f940 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1f950 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1f960 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1f970 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1f980 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1f990 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1f9a0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1f9b0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1f9c0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1f9d0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1f9e0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1f9f0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1fa00 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1fa10 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1fa20 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1fa30 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1fa40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1fa50 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1fa60 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1fa70 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1fa80 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1fa90 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1faa0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1fab0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1fac0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1fad0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1fae0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1faf0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1fb00 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1fb10 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1fb20 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1fb30 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1fb40 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1fb50 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1fb60 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1fb70 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1fb80 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1fb90 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1fba0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1fbb0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1fbc0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1fbd0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1fbe0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1fbf0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1fc00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1fc10 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1fc20 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1fc30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1fc40 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1fc50 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1fc60 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1fc70 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1fc80 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1fc90 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1fca0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1fcb0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1fcc0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72  f the common for
1fcd0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1fce0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1fcf0 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69  dard library pri
1fd00 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73  ntf() .** plus s
1fd10 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1fd20 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1fd30 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c  ats ([%q], [%Q],
1fd40 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29   [%w], and [%z])
1fd50 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75  ..** See the [bu
1fd60 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d  ilt-in printf()]
1fd70 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
1fd80 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a  or details..**.*
1fd90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1fda0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1fdb0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1fdc0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1fdd0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1fde0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1fdf0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1fe00 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a  e3_malloc64()]..
1fe10 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1fe20 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1fe30 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1fe40 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1fe50 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1fe60 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1fe70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1fe80 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1fe90 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1fea0 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61  lloc64()] is una
1feb0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1fec0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1fed0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1fee0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1fef0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1ff00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1ff10 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1ff20 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1ff30 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1ff40 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1ff50 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1ff60 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1ff70 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1ff80 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1ff90 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1ffa0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1ffb0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1ffc0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1ffd0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1ffe0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1fff0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
20000 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
20010 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
20020 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
20030 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
20040 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
20050 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
20060 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
20070 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
20080 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
20090 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
200a0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
200b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
200c0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
200d0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
200e0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
200f0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
20100 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
20110 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
20120 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
20130 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
20140 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
20150 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
20160 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
20170 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
20180 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
20190 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
201a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
201b0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
201c0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
201d0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
201e0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
201f0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
20200 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
20210 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
20220 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
20230 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
20240 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
20250 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
20260 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
20270 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
20280 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
20290 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
202a0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
202b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
202c0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
202d0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
202e0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
202f0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
20300 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
20310 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
20320 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
20330 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
20340 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
20350 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
20360 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tf()..**.** See 
20370 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e  also:  [built-in
20380 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69   printf()], [pri
20390 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ntf() SQL functi
203a0 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  on].*/.char *sql
203b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
203c0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
203d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
203e0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
203f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
20400 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
20410 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
20420 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
20430 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
20440 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
20450 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
20460 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
20470 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
20480 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
20490 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
204a0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
204b0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
204c0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
204d0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
204e0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
204f0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
20500 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
20510 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
20520 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
20530 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
20540 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
20550 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
20560 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
20570 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
20580 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
20590 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
205a0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
205b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
205c0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
205d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
205e0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
205f0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
20600 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
20610 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
20620 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
20630 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
20640 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
20650 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
20660 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
20670 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
20680 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
20690 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
206a0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
206b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
206c0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
206d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
206e0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
206f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
20700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20710 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
20720 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
20730 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
20740 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
20750 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
20760 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
20770 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
20780 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
20790 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
207a0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
207b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
207c0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
207d0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
207e0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
207f0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
20800 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
20810 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
20820 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
20830 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
20840 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
20850 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
20860 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
20870 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
20880 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
20890 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
208a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
208b0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
208c0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
208d0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
208e0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
208f0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
20900 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
20910 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
20920 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
20930 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
20940 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
20950 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
20960 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
20970 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
20980 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
20990 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
209a0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
209b0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
209c0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
209d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
209e0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
209f0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
20a00 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
20a10 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
20a20 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
20a30 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
20a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20a50 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
20a60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
20a70 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
20a80 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
20a90 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
20aa0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
20ab0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
20ac0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20ad0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
20ae0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
20af0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
20b00 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
20b10 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
20b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
20b30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
20b40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20b50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20b60 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
20b70 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
20b80 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
20b90 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
20ba0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
20bb0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
20bc0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
20bd0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
20be0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
20bf0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
20c00 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
20c10 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
20c20 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
20c30 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
20c40 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
20c50 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
20c60 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
20c70 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
20c80 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
20c90 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
20ca0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
20cb0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
20cc0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
20cd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
20ce0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
20cf0 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
20d00 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
20d10 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
20d20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
20d30 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
20d40 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
20d50 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
20d60 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
20d70 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
20d80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20d90 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
20da0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
20db0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
20dc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20dd0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
20de0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
20df0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
20e00 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
20e10 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
20e20 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
20e30 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
20e40 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
20e50 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
20e60 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
20e70 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
20e80 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
20e90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
20ea0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
20eb0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
20ec0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20ed0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
20ee0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
20ef0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
20f00 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
20f10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
20f20 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20f30 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
20f40 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
20f50 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
20f60 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
20f70 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
20f80 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
20f90 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
20fa0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
20fb0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
20fc0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
20fd0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
20fe0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
20ff0 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
21000 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
21010 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
21020 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
21030 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21040 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
21050 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
21060 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
21070 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
21080 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
21090 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
210a0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
210b0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
210c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
210d0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
210e0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
210f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
21100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
21110 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
21120 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
21130 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
21140 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
21150 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
21160 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
21170 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
21180 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
21190 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
211a0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
211b0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
211c0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
211d0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
211e0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
211f0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
21200 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
21210 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
21220 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
21230 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
21240 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
21250 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
21260 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
21270 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
21280 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
21290 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
212a0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
212b0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
212c0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
212d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
212e0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
212f0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
21300 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
21310 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
21320 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
21330 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
21340 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
21350 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
21360 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
21370 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
21380 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
21390 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
213a0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
213b0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
213c0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
213d0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
213e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
213f0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
21400 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
21410 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
21420 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
21430 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
21440 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
21450 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
21460 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
21470 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
21480 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
21490 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
214a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
214b0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
214c0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
214d0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
214e0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
214f0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
21500 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
21510 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
21520 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
21530 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
21540 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
21550 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
21560 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
21570 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
21580 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
21590 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
215a0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
215b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
215c0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
215d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
215e0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
215f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
21600 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
21610 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
21620 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
21630 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
21640 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
21650 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
21660 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
21670 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
21680 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
21690 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
216a0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
216b0 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
216c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
216d0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
216e0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
216f0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
21700 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
21710 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
21720 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
21730 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
21740 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
21750 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
21760 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
21770 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
21780 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
21790 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
217a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
217b0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
217c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
217d0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
217e0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
217f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
21800 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
21810 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
21820 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
21830 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
21840 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
21850 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
21860 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
21870 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
21880 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
21890 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
218a0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
218b0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
218c0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
218d0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
218e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
218f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21900 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21910 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
21920 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
21930 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
21940 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
21950 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
21960 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
21970 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
21980 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
21990 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
219a0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
219b0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
219c0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
219d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
219e0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
219f0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
21a00 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
21a10 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
21a20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
21a30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
21a40 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
21a50 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
21a60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
21a70 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
21a80 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
21a90 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
21aa0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
21ab0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
21ac0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
21ad0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
21ae0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
21af0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
21b00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
21b10 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
21b20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
21b30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
21b40 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
21b50 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
21b60 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
21b70 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
21b80 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
21b90 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
21ba0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
21bb0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
21bc0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
21bd0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
21be0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
21bf0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
21c00 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
21c10 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
21c20 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
21c30 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
21c40 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
21c50 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
21c60 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
21c70 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
21c80 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
21c90 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
21ca0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
21cb0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
21cc0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
21cd0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
21ce0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
21cf0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
21d00 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
21d10 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
21d20 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
21d30 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
21d40 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
21d50 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
21d60 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
21d70 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
21d80 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
21d90 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
21da0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
21db0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
21dc0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
21dd0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
21de0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
21df0 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
21e00 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
21e10 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
21e20 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
21e30 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
21e40 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
21e50 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
21e60 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
21e70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
21e80 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
21e90 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
21ea0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
21eb0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
21ec0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
21ed0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
21ee0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
21ef0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
21f00 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
21f10 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
21f20 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
21f30 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
21f40 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
21f50 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
21f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21f70 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
21f80 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
21f90 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
21fa0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57   sqlite3.** KEYW
21fb0 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65  ORDS: {authorize
21fc0 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a  r callback}.**.*
21fd0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
21fe0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
21ff0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22000 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
22010 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
22020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
22030 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
22040 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
22050 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
22060 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22070 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
22080 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
22090 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
220a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
220b0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
220c0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
220d0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
220e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
220f0 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
22100 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71  repare16()], [sq
22110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22120 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  v2()],.** and [s
22130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22140 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v3()].  ^At var
22150 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
22160 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
22170 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
22180 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
22190 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
221a0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
221b0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
221c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
221d0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
221e0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
221f0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
22200 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
22210 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
22220 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
22230 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
22240 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
22250 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
22260 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
22270 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
22280 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
22290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
222a0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
222b0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
222c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
222d0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
222e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
222f0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
22300 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
22310 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
22320 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
22330 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
22340 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
22350 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
22360 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
22370 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
22380 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
22390 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
223a0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
223b0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
223c0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
223d0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
223e0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
223f0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
22400 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
22410 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
22420 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
22430 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
22440 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
22450 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
22460 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
22470 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
22480 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22490 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
224a0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
224b0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
224c0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
224d0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
224e0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
224f0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
22500 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
22510 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
22520 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
22530 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22540 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
22550 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
22560 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
22570 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
22580 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
22590 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
225a0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
225b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
225c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
225d0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
225e0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
225f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
22600 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
22610 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
22620 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
22630 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
22640 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
22650 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65  e callback are e
22660 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  ither NULL point
22670 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d  ers or zero-term
22680 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a  inated strings.*
22690 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  * that contain a
226a0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
226b0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
226c0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
226d0 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  zed..** Applicat
226e0 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73  ions must always
226f0 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20   be prepared to 
22700 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c  encounter a NULL
22710 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a   pointer in any.
22720 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  ** of the third 
22730 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74  through the sixt
22740 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  h parameters of 
22750 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
22760 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
22770 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
22780 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
22790 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
227a0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
227b0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
227c0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
227d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
227e0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
227f0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
22800 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
22810 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
22820 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
22830 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
22840 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
22850 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
22860 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
22870 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
22880 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
22890 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
228a0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
228b0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
228c0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
228d0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
228e0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e   table..** ^When
228f0 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65   a table is refe
22900 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c  renced by a [SEL
22910 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75  ECT] but no colu
22920 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a  mn values are.**
22930 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
22940 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20  that table (for 
22950 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65  example in a que
22960 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45  ry like.** "SELE
22970 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d  CT count(*) FROM
22980 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20   tab") then the 
22990 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75  [SQLITE_READ] au
229a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
229b0 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  k.** is invoked 
229c0 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61  once for that ta
229d0 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d  ble with a colum
229e0 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61  n name that is a
229f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
22a00 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
22a10 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
22a20 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
22a30 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
22a40 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
22a50 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
22a60 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
22a70 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
22a80 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
22a90 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
22aa0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
22ab0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
22ac0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
22ad0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
22ae0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
22af0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22b00 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
22b10 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22b20 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
22b30 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
22b40 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
22b50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
22b60 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
22b70 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
22b80 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
22b90 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
22ba0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
22bb0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
22bc0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
22bd0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
22be0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
22bf0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
22c00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
22c10 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
22c20 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
22c30 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
22c40 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
22c50 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
22c60 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
22c70 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
22c80 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
22c90 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
22ca0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
22cb0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
22cc0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
22cd0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
22ce0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
22cf0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
22d00 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
22d10 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
22d20 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
22d30 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
22d40 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
22d50 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
22d60 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
22d70 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
22d80 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
22d90 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
22da0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
22db0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
22dc0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
22dd0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
22de0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
22df0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
22e00 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
22e10 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
22e20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
22e30 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
22e40 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
22e50 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
22e60 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
22e70 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
22e80 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
22e90 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
22ea0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
22eb0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
22ec0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
22ed0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
22ee0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
22ef0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
22f00 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
22f10 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
22f20 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
22f30 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
22f40 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
22f50 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
22f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
22f70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22f80 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
22f90 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
22fa0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
22fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22fc0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
22fd0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22fe0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
22ff0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
23000 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
23010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23020 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
23030 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23040 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23050 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23060 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
23070 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
23080 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
23090 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
230a0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
230b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
230c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
230d0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
230e0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
230f0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
23100 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
23110 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
23120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
23130 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
23140 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
23150 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23160 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
23170 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
23180 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23190 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
231a0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
231b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
231c0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
231d0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
231e0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
231f0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
23200 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
23210 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
23220 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
23230 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
23240 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
23250 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
23260 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
23270 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
23280 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
23290 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
232a0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
232b0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
232c0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
232d0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
232e0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
232f0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
23300 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
23310 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
23320 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
23330 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23340 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
23350 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
23360 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
23370 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
23380 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
23390 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
233a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
233b0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
233c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
233d0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
233e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
233f0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
23400 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
23410 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
23420 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
23430 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
23440 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
23450 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
23460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
23470 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
23480 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
23490 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
234a0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
234b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
234c0 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
234d0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
234e0 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
234f0 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
23500 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
23510 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
23520 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
23530 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
23540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23550 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
23560 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
23570 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
23580 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
23590 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
235a0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
235b0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
235c0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
235d0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
235e0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
235f0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
23600 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
23610 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
23620 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
23630 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
23640 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
23650 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
23660 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
23670 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
23680 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
23690 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
236a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
236b0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
236c0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
236d0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
236e0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
236f0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
23700 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
23710 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
23720 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
23730 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
23740 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
23750 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
23760 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
23770 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
23780 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
23790 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
237a0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
237b0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
237c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
237d0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
237e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
237f0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
23800 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
23810 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
23820 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
23830 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
23840 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
23850 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
23860 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
23870 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
23880 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23890 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
238a0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
238b0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
238c0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
238d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
238e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
238f0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
23900 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
23910 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
23920 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
23930 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
23940 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
23950 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
23960 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
23970 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
23980 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
23990 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
239a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
239b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
239c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
239d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
239e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
239f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23a00 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
23a10 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
23a20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23a30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23a40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23a50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
23a60 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
23a70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23a80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23a90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
23aa0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
23ab0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
23ac0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
23ad0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23ae0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
23af0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
23b00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23b10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23b20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23b30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
23b40 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
23b50 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23b60 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23b70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23b80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
23b90 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
23ba0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
23bb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23bc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23bd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
23be0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
23bf0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
23c00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23c20 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
23c30 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
23c40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
23c50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23c70 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
23c80 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
23c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23ca0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23cc0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
23cd0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
23ce0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
23cf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23d10 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
23d20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
23d30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
23d40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23d60 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
23d70 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
23d80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
23d90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
23da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23db0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
23dc0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
23dd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23de0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23e00 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
23e10 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
23e20 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
23e30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23e50 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
23e60 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
23e70 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
23e80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23ea0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
23eb0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
23ec0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
23ed0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23ef0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
23f00 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
23f10 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
23f20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23f30 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
23f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
23f50 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
23f60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23f70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23f80 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
23f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
23fa0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
23fb0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
23fc0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
23fd0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
23fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
23ff0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
24000 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
24010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24020 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
24030 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
24040 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
24050 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24070 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
24080 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
24090 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
240a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
240b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
240c0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
240d0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
240e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
240f0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
24100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24110 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
24120 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
24130 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
24140 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24160 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
24170 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
24180 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
24190 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
241a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
241b0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
241c0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
241d0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
241e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
241f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24200 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
24210 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
24220 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
24230 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24250 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
24260 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
24270 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24280 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
242a0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
242b0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
242c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
242d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
242e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
242f0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
24300 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
24310 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
24320 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
24330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
24340 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
24350 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
24360 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
24370 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
24380 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
24390 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
243a0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
243b0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
243c0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
243d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
243e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
243f0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
24400 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
24410 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
24420 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
24430 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
24440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24450 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
24460 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
24470 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
24480 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
24490 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
244a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
244b0 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  s are deprecated
244c0 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
244d0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69  e3_trace_v2()] i
244e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74  nterface.** inst
244f0 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69  ead of the routi
24500 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65  nes described he
24510 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  re..**.** These 
24520 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
24530 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
24540 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
24550 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
24560 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
24570 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
24580 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
24590 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
245a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
245b0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
245c0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
245d0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
245e0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
245f0 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
24600 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
24610 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
24620 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
24630 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
24640 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24650 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
24660 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
24670 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
24680 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
24690 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
246a0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
246b0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
246c0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
246d0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
246e0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
246f0 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
24700 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
24710 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
24720 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
24730 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
24740 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
24750 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
24760 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
24770 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
24780 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
24790 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
247a0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
247b0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
247c0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
247d0 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
247e0 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
247f0 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
24800 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
24810 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
24820 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
24830 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
24840 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
24850 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
24860 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
24870 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
24880 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
24890 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
248a0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
248b0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
248c0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
248d0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
248e0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
248f0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
24900 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
24910 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
24920 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
24930 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
24940 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
24950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
24960 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
24970 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
24980 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
24990 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
249a0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
249b0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
249c0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
249d0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
249e0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
249f0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
24a00 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
24a10 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
24a20 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
24a30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
24a40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
24a50 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
24a60 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
24a70 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
24a80 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
24a90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
24aa0 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
24ab0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
24ac0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
24ad0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63  ,.   void(*xTrac
24ae0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
24af0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
24b00 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
24b10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
24b20 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
24b30 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
24b40 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
24b50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
24b60 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
24b70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b80 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
24b90 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
24ba0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
24bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24bc0 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
24bd0 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
24be0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
24bf0 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
24c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
24c10 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
24c20 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61   logic.  The M a
24c30 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
24c40 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24c50 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20  D,M,X,P)] is an 
24c60 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
24c70 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
24c80 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
24c90 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
24ca0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
24cb0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
24cc0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
24cd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
24ce0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
24cf0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
24d00 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
24d10 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
24d20 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
24d30 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
24d40 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
24d50 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
24d60 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
24d70 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
24d80 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
24d90 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
24da0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
24db0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
24dc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
24dd0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
24de0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
24df0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
24e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
24e10 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
24e20 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
24e30 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
24e40 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
24e50 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
24e60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
24e70 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
24e80 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
24e90 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
24ea0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
24eb0 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
24ec0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
24ed0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
24ee0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
24ef0 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
24f00 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
24f10 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
24f20 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
24f30 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
24f40 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
24f50 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
24f60 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
24f70 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
24f80 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24f90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24fa0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24fb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
24fc0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
24fd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24fe0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
24ff0 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
25000 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
25010 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
25020 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
25030 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
25040 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
25050 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
25060 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
25070 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
25080 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
25090 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
250a0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
250b0 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
250c0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
250d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
250e0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
250f0 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
25100 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
25110 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
25120 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
25130 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
25140 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
25150 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
25160 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
25170 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
25180 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
25190 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
251a0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
251b0 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
251c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
251d0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
251e0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
251f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
25200 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
25210 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
25220 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25230 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25240 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
25250 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
25260 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
25270 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
25280 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
25290 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
252a0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
252b0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
252c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
252d0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
252e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
252f0 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
25300 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
25310 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
25320 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
25330 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
25340 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
25350 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
25360 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
25370 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
25380 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
25390 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
253a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
253b0 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
253c0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
253d0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
253e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
253f0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
25400 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
25410 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
25420 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
25430 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
25440 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
25450 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25460 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
25470 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
25480 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
25490 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
254a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
254b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
254c0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
254d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
254e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
254f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
25500 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
25510 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
25520 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
25530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
25540 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
25550 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
25560 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
25570 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
25580 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
25590 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
255a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
255b0 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
255c0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
255d0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
255e0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
255f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
25600 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
25610 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
25620 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
25630 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
25640 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
25650 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
25660 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
25670 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
25680 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
25690 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
256a0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
256b0 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
256c0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
256d0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
256e0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
256f0 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
25700 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
25710 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
25720 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
25730 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
25740 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
25750 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
25760 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
25770 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
25780 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
25790 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
257a0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
257b0 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
257c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
257d0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
257e0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
257f0 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
25800 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
25810 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
25820 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
25830 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
25840 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
25850 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
25860 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
25870 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
25880 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
25890 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
258a0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
258b0 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
258c0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
258d0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
258e0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
258f0 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
25900 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
25910 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
25920 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
25930 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
25940 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
25950 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
25960 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
25970 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
25980 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
25990 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
259a0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
259b0 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
259c0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
259d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
259e0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
259f0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
25a00 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
25a10 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
25a20 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
25a30 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
25a40 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
25a50 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
25a60 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
25a70 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
25a80 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
25a90 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
25aa0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
25ab0 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
25ac0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
25ad0 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
25ae0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
25af0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
25b00 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
25b10 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
25b20 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
25b30 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
25b40 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
25b50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
25b60 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
25b70 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
25b80 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
25b90 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
25ba0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
25bb0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
25bc0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
25bd0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
25be0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
25bf0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
25c00 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
25c10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
25c20 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
25c30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
25c50 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
25c60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25c70 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
25c80 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
25c90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
25ca0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
25cb0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
25cc0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
25cd0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
25ce0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
25cf0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
25d00 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
25d10 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
25d20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
25d30 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
25d40 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
25d50 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
25d60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
25d70 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
25d80 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
25d90 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
25da0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
25db0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
25dc0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
25dd0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
25de0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
25df0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
25e00 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
25e10 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
25e20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
25e30 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
25e40 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
25e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25e60 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
25e70 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
25e80 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
25e90 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
25ea0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
25eb0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
25ec0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
25ed0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
25ee0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
25ef0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
25f00 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
25f10 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
25f20 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
25f30 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
25f40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
25f50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
25f60 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
25f70 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
25f80 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
25f90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
25fa0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
25fb0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
25fc0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
25fd0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
25fe0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
25ff0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
26000 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
26010 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
26020 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
26030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
26040 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
26050 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
26060 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
26070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26080 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
26090 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
260a0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
260b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
260c0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
260d0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
260e0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
260f0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
26100 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
26110 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
26120 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
26130 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
26140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
26150 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
26160 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
26170 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
26180 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
26190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
261a0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
261b0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
261c0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
261d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
261e0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
261f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
26200 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26210 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
26220 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
26230 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26240 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
26250 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
26260 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
26270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26280 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
26290 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
262a0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
262b0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
262c0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
262d0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
262e0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
262f0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
26300 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
26310 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
26320 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
26330 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
26340 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
26350 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
26360 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
26370 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
26380 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
26390 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
263a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
263b0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
263c0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
263d0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
263e0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
263f0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
26400 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
26410 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
26420 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
26430 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
26440 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
26450 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
26460 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
26470 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
26480 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
26490 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
264a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
264b0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
264c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
264d0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
264e0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
264f0 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
26500 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
26510 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
26520 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
26530 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26540 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
26550 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
26560 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
26570 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
26580 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
26590 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
265a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
265b0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
265c0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
265d0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
265e0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
265f0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
26600 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
26610 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
26620 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
26630 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
26640 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
26650 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
26660 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
26670 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
26680 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
26690 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
266a0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
266b0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
266c0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
266d0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
266e0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
266f0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
26700 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
26710 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
26720 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
26730 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
26740 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
26750 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
26760 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
26770 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
26780 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
26790 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
267a0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
267b0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
267c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
267d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
267e0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
267f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26800 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
26810 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
26820 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
26830 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
26840 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
26850 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
26860 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
26870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26880 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26890 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
268a0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
268b0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
268c0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
268d0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
268e0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
268f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
26900 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
26910 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
26920 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
26930 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
26940 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
26950 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
26960 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
26970 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
26980 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
26990 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
269a0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
269b0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
269c0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
269d0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
269e0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
269f0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
26a00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
26a10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
26a20 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
26a30 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
26a40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
26a50 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26a60 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
26a70 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
26a80 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
26a90 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
26aa0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
26ab0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
26ac0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
26ad0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
26ae0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
26af0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
26b00 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
26b10 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
26b20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26b30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
26b40 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
26b50 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
26b60 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
26b70 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
26b80 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
26b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
26ba0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
26bb0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
26bc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
26bd0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
26be0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
26bf0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
26c00 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
26c10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26c20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
26c30 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
26c40 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
26c50 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
26c60 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
26c70 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
26c80 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
26c90 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
26ca0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
26cb0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
26cc0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
26cd0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
26ce0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
26d00 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
26d10 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
26d20 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
26d30 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
26d40 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
26d50 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
26d60 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
26d70 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
26d80 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26d90 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
26da0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
26db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
26dc0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
26dd0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
26de0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
26df0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26e00 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
26e10 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
26e20 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
26e30 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
26e40 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
26e50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
26e60 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
26e70 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
26e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26e90 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
26ea0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
26eb0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
26ec0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
26ed0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
26ee0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
26ef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26f00 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
26f10 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
26f20 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
26f30 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
26f40 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
26f50 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
26f60 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
26f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26f80 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
26f90 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
26fa0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
26fb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
26fc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
26fd0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
26fe0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
26ff0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
27000 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
27010 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
27020 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
27030 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
27040 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
27050 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
27060 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
27070 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
27080 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
27090 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
270a0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
270b0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
270c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
270d0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
270e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
270f0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
27100 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
27110 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
27120 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
27130 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
27140 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
27150 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
27160 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
27170 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
27180 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
27190 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
271a0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
271b0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
271c0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
271d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
271e0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
271f0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
27200 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
27210 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
27220 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
27230 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
27240 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
27250 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
27260 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
27270 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
27280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27290 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
272a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
272b0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
272c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
272d0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
272e0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
272f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
27300 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
27310 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
27320 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
27330 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
27340 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
27350 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
27360 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
27370 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
27380 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
27390 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
273a0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
273b0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
273c0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
273d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
273e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
273f0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
27400 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
27410 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
27420 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
27430 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
27440 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
27450 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
27460 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
27470 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
27480 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
27490 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c  tion..** URI fil
274a0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
274b0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
274c0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
274d0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
274e0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
274f0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
27500 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
27510 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
27520 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
27530 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
27540 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
27550 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
27560 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
27570 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
27580 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
27590 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
275a0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
275b0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
275c0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
275d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
275e0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
275f0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
27600 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
27610 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
27620 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
27630 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
27640 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27650 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
27660 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
27670 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
27680 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
27690 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
276a0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
276b0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
276c0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
276d0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
276e0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
276f0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
27700 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
27710 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
27720 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
27730 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
27740 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
27750 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
27760 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
27770 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
27780 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
27790 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
277a0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
277b0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
277c0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
277d0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
277e0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
277f0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
27800 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
27810 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
27820 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
27830 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
27840 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
27850 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
27860 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
27870 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
27880 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
27890 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
278a0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
278b0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
278c0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
278d0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
278e0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
278f0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
27900 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
27910 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
27920 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
27930 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
27940 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
27950 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
27960 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
27970 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
27980 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
27990 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
279a0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
279b0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
279c0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
279d0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
279e0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
279f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
27a00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
27a10 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
27a20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
27a30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27a40 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
27a50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
27a60 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
27a70 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
27a80 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
27a90 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
27aa0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
27ab0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
27ac0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
27ad0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
27ae0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
27af0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
27b00 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
27b10 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
27b20 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
27b30 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
27b40 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
27b50 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
27b60 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
27b70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27b80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27b90 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
27ba0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
27bb0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
27bc0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
27bd0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
27be0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
27bf0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
27c00 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
27c10 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
27c20 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
27c30 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
27c40 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
27c50 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
27c60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27c70 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
27c80 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27c90 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
27ca0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
27cb0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
27cc0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
27cd0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
27ce0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27cf0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
27d00 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
27d10 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
27d20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
27d30 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27d40 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
27d50 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
27d60 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
27d70 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
27d80 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
27d90 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
27da0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
27db0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
27dc0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
27dd0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
27de0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
27df0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
27e00 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
27e10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27e20 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
27e30 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
27e40 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
27e50 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
27e60 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
27e70 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
27e80 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
27e90 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
27ea0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
27eb0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
27ec0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
27ed0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
27ee0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
27ef0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
27f00 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
27f10 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
27f20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
27f30 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
27f40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27f50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27f60 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
27f70 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
27f80 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
27f90 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
27fa0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
27fb0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
27fc0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
27fd0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
27fe0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
27ff0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
28000 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
28010 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
28020 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
28030 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
28040 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
28050 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
28060 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
28070 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
28080 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
28090 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
280a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
280b0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
280c0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
280d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
280e0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
280f0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
28100 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
28110 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
28120 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
28130 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
28140 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
28150 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
28160 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
28170 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
28180 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
28190 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
281a0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
281b0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
281c0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
281d0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
281e0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
281f0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
28200 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
28210 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
28220 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
28230 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
28240 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
28250 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
28260 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
28270 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
28280 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
28290 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
282a0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
282b0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
282c0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
282d0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
282e0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
282f0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
28300 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
28310 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
28320 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
28330 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
28340 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
28350 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
28360 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
28370 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
28380 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
28390 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
283a0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
283b0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
283c0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
283d0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
283e0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
283f0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
28400 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
28410 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
28420 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
28430 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
28440 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
28450 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
28460 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
28470 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
28480 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
28490 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
284a0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
284b0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
284c0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
284d0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
284e0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
284f0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
28500 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
28510 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
28520 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
28530 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
28540 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
28550 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
28560 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
28570 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
28580 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
28590 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
285a0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
285b0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
285c0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
285d0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
285e0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
285f0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
28600 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
28610 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
28620 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
28630 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
28640 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
28650 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
28660 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
28670 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
28680 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
28690 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
286a0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
286b0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
286c0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
286d0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
286e0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
286f0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
28700 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
28710 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
28720 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
28730 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
28740 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
28750 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
28760 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
28770 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
28780 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
28790 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
287a0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
287b0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
287c0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
287d0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
287e0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
287f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
28800 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
28810 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
28820 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
28830 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
28840 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
28850 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
28860 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
28870 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
28880 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
28890 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
288a0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
288b0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
288c0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
288d0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
288e0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
288f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
28900 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
28910 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
28920 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
28930 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
28940 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
28950 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
28960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
28970 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
28980 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
28990 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
289a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
289b0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
289c0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
289d0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
289e0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
289f0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
28a00 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
28a10 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
28a20 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
28a30 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
28a40 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
28a50 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
28a60 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
28a70 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
28a80 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
28a90 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
28aa0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
28ab0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
28ac0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
28ad0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
28ae0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
28af0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
28b00 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
28b10 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
28b20 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
28b30 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
28b40 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
28b50 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
28b60 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
28b70 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
28b80 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
28b90 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
28ba0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
28bb0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
28bc0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
28bd0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
28be0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
28bf0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
28c00 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
28c10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
28c20 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
28c30 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
28c40 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
28c50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
28c60 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
28c70 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
28c80 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
28c90 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
28ca0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
28cb0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
28cc0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
28cd0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
28ce0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
28cf0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28d00 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
28d10 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
28d20 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
28d30 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
28d40 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
28d50 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
28d60 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
28d70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
28d80 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
28d90 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
28da0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
28db0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
28dc0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
28dd0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
28de0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
28df0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
28e00 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
28e10 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
28e20 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
28e30 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
28e40 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
28e50 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
28e60 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
28e70 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
28e80 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
28e90 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
28ea0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
28eb0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
28ec0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
28ed0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
28ee0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
28ef0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
28f00 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
28f10 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
28f20 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
28f30 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
28f40 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
28f50 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
28f60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28f70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
28f80 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
28f90 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
28fa0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
28fb0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
28fc0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
28fd0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
28fe0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28ff0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
29000 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
29010 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
29020 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
29030 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
29040 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
29050 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
29060 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29070 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
29080 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
29090 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
290a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
290b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
290c0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
290d0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
290e0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
290f0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
29100 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
29110 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
29120 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
29130 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
29140 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
29150 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
29160 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
29170 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
29180 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
29190 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
291a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
291b0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
291c0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
291d0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
291e0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
291f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
29200 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
29210 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
29220 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
29230 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
29240 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
29250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
29260 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
29270 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
29280 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
29290 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
292a0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
292b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
292c0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
292d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
292e0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
292f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
29300 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
29310 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
29320 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
29330 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
29340 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
29350 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
29360 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
29370 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
29380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
29390 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
293a0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
293b0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
293c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
293d0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
293e0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
293f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
29400 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
29410 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
29420 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
29430 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
29440 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
29450 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
29460 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
29470 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
29480 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
29490 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
294a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
294b0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
294c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
294d0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
294e0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
294f0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
29500 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
29510 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
29520 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
29530 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
29540 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
29550 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
29560 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
29570 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
29580 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
29590 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
295a0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
295b0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
295c0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
295d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
295e0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
295f0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
29600 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
29610 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
29620 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
29630 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
29640 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
29650 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
29660 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
29670 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
29680 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
29690 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
296a0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
296b0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
296c0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
296d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
296e0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
296f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
29700 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29710 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
29720 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
29730 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
29740 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
29750 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
29760 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
29770 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
29780 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
29790 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
297a0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
297b0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
297c0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
297d0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
297e0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
297f0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
29800 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
29810 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
29820 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
29830 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
29840 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
29850 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
29860 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
29870 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
29880 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
29890 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
298a0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
298b0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
298c0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
298d0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
298e0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
298f0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
29900 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
29910 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
29920 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
29930 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
29940 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
29950 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
29960 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
29970 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
29980 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
29990 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
299a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
299b0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
299c0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
299d0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
299e0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
299f0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
29a00 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
29a10 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
29a20 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
29a30 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
29a40 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
29a50 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
29a60 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
29a70 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
29a80 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
29a90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
29aa0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
29ab0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
29ac0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
29ad0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
29ae0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
29af0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
29b00 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
29b10 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
29b20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
29b30 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
29b40 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
29b50 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
29b60 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
29b70 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
29b80 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
29b90 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
29ba0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
29bb0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
29bc0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29bd0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
29be0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
29bf0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
29c00 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
29c10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
29c20 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
29c30 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
29c40 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
29c50 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
29c60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
29c70 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
29c80 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
29c90 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
29ca0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
29cb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
29cc0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
29cd0 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
29ce0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
29cf0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
29d00 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
29d10 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
29d20 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
29d30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29d40 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
29d50 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
29d60 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
29d70 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
29d80 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
29d90 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
29da0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
29db0 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
29dc0 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  all..** ^The sql
29dd0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
29de0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
29df0 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
29e00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
29e10 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
29e20 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
29e30 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
29e40 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
29e50 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
29e60 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
29e70 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20  *.** The values 
29e80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
29e90 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e  te3_errcode() an
29ea0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
29eb0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
29ec0 28 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  () might change 
29ed0 77 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61  with each API ca
29ee0 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74  ll..** Except, t
29ef0 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e  here are some in
29f00 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
29f10 65 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  e guaranteed to 
29f20 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20  never.** change 
29f30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
29f40 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68   error code.  Th
29f50 65 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65  e error-code pre
29f60 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72  serving.** inter
29f70 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a  faces are:.**.**
29f80 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71   <ul>.** <li> sq
29f90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a  lite3_errcode().
29fa0 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
29fb0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
29fc0 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
29fd0 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c  e3_errmsg().** <
29fe0 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  li> sqlite3_errm
29ff0 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a  sg16().** </ul>.
2a000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a010 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
2a020 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
2a030 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
2a040 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
2a050 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
2a060 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
2a070 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
2a080 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
2a090 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
2a0a0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
2a0b0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
2a0c0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
2a0d0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
2a0e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
2a0f0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
2a100 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
2a110 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
2a120 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
2a130 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
2a140 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
2a150 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
2a160 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
2a170 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
2a180 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
2a190 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
2a1a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2a1b0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
2a1c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
2a1d0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
2a1e0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
2a1f0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
2a200 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
2a210 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
2a220 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
2a230 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2a240 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
2a250 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
2a260 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
2a270 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2a280 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
2a290 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
2a2a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
2a2b0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
2a2c0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
2a2d0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
2a2e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
2a2f0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
2a300 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
2a310 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
2a320 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
2a330 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
2a340 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
2a350 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
2a360 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
2a370 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2a380 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
2a390 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
2a3a0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
2a3b0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
2a3c0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
2a3d0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
2a3e0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
2a3f0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
2a400 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
2a410 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
2a420 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
2a430 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
2a440 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
2a450 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
2a460 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
2a470 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
2a480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
2a490 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
2a4a0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
2a4b0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
2a4c0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
2a4d0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
2a4e0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
2a4f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
2a500 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2a510 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
2a520 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
2a530 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
2a540 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
2a550 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
2a560 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
2a570 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
2a580 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
2a590 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
2a5a0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
2a5b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
2a5c0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2a5d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2a5e0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
2a5f0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
2a600 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a610 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
2a620 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2a630 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2a640 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
2a650 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2a660 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
2a670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2a680 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2a690 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2a6a0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
2a6b0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
2a6c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
2a6d0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
2a6e0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
2a6f0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
2a700 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
2a710 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
2a720 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
2a730 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
2a740 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
2a750 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
2a760 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
2a770 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
2a780 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
2a790 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
2a7a0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2a7b0 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
2a7c0 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
2a7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
2a7e0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
2a7f0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
2a800 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
2a810 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
2a820 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
2a830 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
2a840 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
2a850 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
2a860 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
2a870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a880 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
2a890 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
2a8a0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2a8b0 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
2a8c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a8d0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
2a8e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a8f0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
2a900 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
2a910 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
2a920 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a930 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
2a940 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
2a950 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
2a960 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a970 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
2a980 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2a990 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
2a9a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a9b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2a9c0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
2a9d0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
2a9e0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
2a9f0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
2aa00 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
2aa10 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
2aa20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2aa30 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
2aa40 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
2aa50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
2aa60 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
2aa70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aa80 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
2aa90 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
2aaa0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
2aab0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
2aac0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
2aad0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
2aae0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
2aaf0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
2ab00 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
2ab10 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
2ab20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2ab30 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2ab40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
2ab50 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
2ab60 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
2ab70 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
2ab80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
2ab90 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
2aba0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
2abb0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
2abc0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
2abd0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
2abe0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
2abf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ac00 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
2ac10 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
2ac20 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
2ac30 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
2ac40 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
2ac50 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
2ac60 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
2ac70 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
2ac80 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
2ac90 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
2aca0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
2acb0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
2acc0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
2acd0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
2ace0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
2acf0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
2ad00 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
2ad10 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
2ad20 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
2ad30 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
2ad40 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
2ad50 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
2ad60 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
2ad70 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
2ad80 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
2ad90 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
2ada0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
2adb0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
2adc0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
2add0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
2ade0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2adf0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
2ae00 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
2ae10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
2ae20 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
2ae30 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
2ae40 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
2ae50 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
2ae60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
2ae70 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
2ae80 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
2ae90 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
2aea0 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
2aeb0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
2aec0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2aed0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
2aee0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
2aef0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
2af00 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
2af10 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
2af20 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
2af30 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
2af40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
2af50 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
2af60 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
2af70 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
2af80 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2af90 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
2afa0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
2afb0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
2afc0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
2afd0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
2afe0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
2aff0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
2b000 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
2b010 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
2b020 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
2b030 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
2b040 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
2b050 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
2b060 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
2b070 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
2b080 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
2b090 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
2b0a0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
2b0b0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
2b0c0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
2b0d0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
2b0e0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
2b0f0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
2b100 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
2b110 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
2b120 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
2b130 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
2b140 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
2b150 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
2b160 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
2b170 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
2b180 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
2b190 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2b1a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
2b1b0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
2b1c0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
2b1d0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2b1e0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
2b1f0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
2b200 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
2b210 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
2b220 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2b230 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
2b240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
2b250 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
2b260 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
2b270 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2b280 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
2b290 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
2b2a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
2b2b0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
2b2c0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
2b2d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2b2e0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2b2f0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
2b300 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
2b310 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
2b320 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2b330 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
2b340 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
2b350 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
2b360 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
2b370 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
2b380 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
2b390 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2b3a0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
2b3b0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
2b3c0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
2b3d0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2b3e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2b3f0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2b400 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b410 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2b420 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
2b430 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
2b440 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
2b450 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
2b460 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b470 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2b480 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2b490 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2b4a0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b4b0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2b4c0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
2b4d0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
2b4e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b4f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2b500 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
2b510 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
2b520 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2b530 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2b540 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
2b550 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
2b560 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
2b570 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2b580 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
2b590 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2b5a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
2b5b0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
2b5c0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
2b5d0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
2b5e0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b5f0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b600 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2b610 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b620 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b630 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2b640 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
2b650 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
2b660 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
2b670 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b680 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2b690 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2b6a0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2b6b0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
2b6c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b6d0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2b6e0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
2b6f0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
2b700 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2b710 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2b720 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
2b730 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
2b740 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2b750 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2b760 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
2b770 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
2b780 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
2b790 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2b7a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2b7b0 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
2b7c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2b7d0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
2b7e0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
2b7f0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
2b800 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
2b810 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
2b820 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
2b830 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
2b840 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
2b850 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
2b860 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2b880 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
2b890 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
2b8a0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
2b8b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b8c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
2b8d0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
2b8e0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
2b8f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b900 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
2b910 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2b920 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
2b930 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b940 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
2b950 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
2b960 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
2b970 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
2b980 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2b990 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
2b9a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b9b0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2b9c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2b9d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
2b9e0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
2b9f0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
2ba00 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
2ba10 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
2ba20 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2ba30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ba40 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2ba50 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2ba60 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ba70 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
2ba80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2ba90 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
2baa0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
2bab0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
2bac0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
2bad0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2bae0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
2baf0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
2bb00 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
2bb10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2bb20 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
2bb30 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
2bb40 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
2bb50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bb60 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2bb70 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2bb80 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2bb90 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
2bba0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2bbb0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
2bbc0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
2bbd0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
2bbe0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bbf0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
2bc00 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
2bc10 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2bc20 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
2bc30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bc40 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
2bc50 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2bc60 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2bc70 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2bc80 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2bc90 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
2bca0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2bcb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2bcc0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2bcd0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2bce0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2bcf0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
2bd00 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
2bd10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
2bd20 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
2bd30 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
2bd40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
2bd50 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
2bd60 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
2bd70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bd80 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
2bd90 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
2bda0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2bdb0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2bdc0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
2bdd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2bde0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2bdf0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
2be00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2be10 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2be20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2be30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2be40 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2be50 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2be60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2be70 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a   Prepare Flags.*
2be80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2be90 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2bea0 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
2beb0 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
2bec0 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22  o.** "prepFlags"
2bed0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2bee0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2bef0 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20  re_v3()] and.** 
2bf00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bf10 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61  16_v3()] interfa
2bf20 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66  ces..**.** New f
2bf30 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65  lags may be adde
2bf40 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2bf50 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
2bf60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2bf70 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2bf80 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64  ERSISTENT]] ^(<d
2bf90 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2bfa0 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e  _PERSISTENT</dt>
2bfb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2bfc0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2bfd0 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20  STENT flag is a 
2bfe0 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72  hint to the quer
2bff0 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61  y planner.** tha
2c000 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2c010 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2c020 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20   retained for a 
2c030 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a  long time and.**
2c040 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64   probably reused
2c050 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e   many times.)^ ^
2c060 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61  Without this fla
2c070 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  g, [sqlite3_prep
2c080 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64  are_v3()].** and
2c090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c0a0 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65  e16_v3()] assume
2c0b0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2c0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2c0d0 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75  l .** be used ju
2c0e0 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f  st once or at mo
2c0f0 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61  st a few times a
2c100 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  nd then destroye
2c110 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2c120 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c130 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e  relatively soon.
2c140 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   The current imp
2c150 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73  lementation acts
2c160 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  .** on this hint
2c170 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65   by avoiding the
2c180 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69   use of [lookasi
2c190 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73  de memory] so as
2c1a0 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65   not to.** deple
2c1b0 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73  te the limited s
2c1c0 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  tore of lookasid
2c1d0 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65  e memory. Future
2c1e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20   versions of.** 
2c1f0 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f  SQLite may act o
2c200 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66  n this hint diff
2c210 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b  erently..**.** [
2c220 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2c230 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20 5e 28 3c 64  NORMALIZE]] ^(<d
2c240 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2c250 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a  _NORMALIZE</dt>.
2c260 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2c270 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c  E_PREPARE_NORMAL
2c280 49 5a 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  IZE flag indicat
2c290 65 73 20 74 68 61 74 20 61 20 6e 6f 72 6d 61 6c  es that a normal
2c2a0 69 7a 65 64 0a 2a 2a 20 72 65 70 72 65 73 65 6e  ized.** represen
2c2b0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  tation of the SQ
2c2c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 68 6f 75  L statement shou
2c2d0 6c 64 20 62 65 20 63 61 6c 63 75 6c 61 74 65 64  ld be calculated
2c2e0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 61 73 73   and then.** ass
2c2f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2c300 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c310 65 6e 74 2c 20 77 68 69 63 68 20 63 61 6e 20 62  ent, which can b
2c320 65 20 6f 62 74 61 69 6e 65 64 20 76 69 61 0a 2a  e obtained via.*
2c330 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  * the [sqlite3_n
2c340 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d  ormalized_sql()]
2c350 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
2c360 20 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20   semantics used 
2c370 74 6f 0a 2a 2a 20 6e 6f 72 6d 61 6c 69 7a 65 20  to.** normalize 
2c380 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
2c390 61 72 65 20 75 6e 73 70 65 63 69 66 69 65 64 20  are unspecified 
2c3a0 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
2c3b0 68 61 6e 67 65 2e 0a 2a 2a 20 41 74 20 61 20 6d  hange..** At a m
2c3c0 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20  inimum, literal 
2c3d0 76 61 6c 75 65 73 20 77 69 6c 6c 20 62 65 20 72  values will be r
2c3e0 65 70 6c 61 63 65 64 20 77 69 74 68 20 73 75 69  eplaced with sui
2c3f0 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f  table.** placeho
2c400 6c 64 65 72 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  lders..** </dl>.
2c410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c420 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2c430 54 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  TENT            
2c440 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
2c450 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2c460 52 4d 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20  RMALIZE         
2c470 20 20 20 20 20 20 30 78 30 32 0a 0a 2f 2a 0a 2a        0x02../*.*
2c480 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2c490 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2c4a0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2c4b0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2c4c0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2c4d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2c4e0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2c4f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c500 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2c510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c520 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2c530 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2c540 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2c550 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2c560 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2c570 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2c580 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2c590 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2c5a0 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2c5b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c5c0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2c5d0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2c5e0 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2c5f0 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2c600 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2c610 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2c620 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2c630 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2c640 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2c650 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2c660 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2c670 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2c680 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2c690 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2c6a0 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2c6b0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2c6c0 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2c6d0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2c6e0 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2c6f0 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2c700 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2c710 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2c720 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2c730 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2c740 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2c750 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2c760 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2c770 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2c780 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2c790 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2c7a0 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2c7b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2c7c0 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2c7d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2c7e0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2c7f0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2c800 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2c810 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2c820 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2c830 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c840 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2c850 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2c860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2c870 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2c880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c890 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2c8a0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2c8b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2c8c0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2c8d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2c8e0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2c8f0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2c900 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2c910 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2c920 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2c930 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c940 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2c950 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2c960 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2c970 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2c980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2c990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c9a0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2c9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c9c0 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2c9d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2c9e0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2c9f0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2ca00 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2ca10 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2ca20 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2ca30 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2ca40 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2ca50 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2ca60 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2ca70 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2ca80 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2ca90 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2caa0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2cab0 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2cac0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2cad0 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2cae0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2caf0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2cb00 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2cb10 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2cb20 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2cb30 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2cb40 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2cb50 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2cb60 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cb70 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2cb80 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2cb90 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2cba0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2cbb0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2cbc0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2cbd0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2cbe0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2cbf0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2cc00 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2cc10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2cc20 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2cc30 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2cc40 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2cc50 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2cc60 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2cc70 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2cc80 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2cc90 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2cca0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2ccb0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2ccc0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2ccd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cce0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2ccf0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2cd00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2cd10 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2cd20 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2cd30 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2cd40 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2cd50 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2cd60 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2cd70 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2cd80 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2cd90 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2cda0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2cdb0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2cdc0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2cdd0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2cde0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2cdf0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2ce00 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2ce10 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2ce20 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2ce30 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2ce40 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2ce50 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2ce60 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2ce70 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2ce80 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2ce90 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2cea0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2ceb0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2cec0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2ced0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2cee0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2cef0 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2cf00 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2cf10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cf20 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2cf30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cf40 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2cf50 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2cf60 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2cf70 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2cf80 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2cf90 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2cfa0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2cfb0 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2cfc0 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2cfd0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2cfe0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2cff0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2d000 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2d010 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2d020 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2d030 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2d040 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2d050 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2d060 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2d070 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2d080 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2d090 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2d0a0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2d0b0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2d0c0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2d0d0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2d0e0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2d0f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2d100 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2d110 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2d120 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2d130 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2d140 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2d150 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2d160 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2d170 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2d180 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2d190 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2d1a0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2d1b0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2d1c0 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2d1d0 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2d1e0 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2d1f0 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2d200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2d210 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2d220 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2d230 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2d240 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2d250 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2d260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2d270 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2d280 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2d290 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2d2a0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2d2b0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2d2c0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2d2d0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2d2e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2d2f0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2d300 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2d310 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2d320 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2d330 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2d340 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2d350 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2d360 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2d370 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2d380 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2d390 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2d3a0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2d3b0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2d3c0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2d3d0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2d3e0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2d3f0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2d400 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2d410 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2d420 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2d430 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2d440 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2d450 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2d460 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2d470 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2d480 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2d490 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2d4a0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2d4b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2d4c0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2d4d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2d4e0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2d4f0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2d500 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2d510 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2d520 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d530 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2d540 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2d550 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2d560 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2d570 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2d580 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2d590 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2d5a0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2d5b0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2d5c0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2d5d0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2d5e0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2d5f0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2d600 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2d610 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2d620 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2d630 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2d640 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2d650 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2d660 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2d670 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2d680 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2d690 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2d6a0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2d6b0 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
2d6c0 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72  * <p>^sqlite3_pr
2d6d0 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65  epare_v3() diffe
2d6e0 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rs from sqlite3_
2d6f0 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c  prepare_v2() onl
2d700 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74  y in having.** t
2d710 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61  he extra prepFla
2d720 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  gs parameter, wh
2d730 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72  ich is a bit arr
2d740 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66  ay consisting of
2d750 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65   zero or.** more
2d760 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2d770 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2d780 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52  NT|SQLITE_PREPAR
2d790 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68  E_*] flags.  ^Th
2d7a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  e.** sqlite3_pre
2d7b0 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66  pare_v2() interf
2d7c0 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ace works exactl
2d7d0 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  y the same as.**
2d7e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d7f0 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72  _v3() with a zer
2d800 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  o prepFlags para
2d810 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  meter..*/.int sq
2d820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2d830 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d840 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d850 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d860 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2d870 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d880 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2d890 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2d8a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2d8b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2d8c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2d8d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2d8e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2d8f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2d900 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2d910 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d920 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2d930 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2d940 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2d950 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2d960 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d970 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2d980 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2d990 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2d9a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2d9b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2d9c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2d9d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2d9e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d9f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2da00 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2da10 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2da20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2da30 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2da40 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2da50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2da60 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2da70 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2da80 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2da90 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2daa0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2dab0 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c  repare_v3(.  sql
2dac0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2dad0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2dae0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2daf0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2db00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2db10 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2db20 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2db30 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2db40 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2db50 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2db60 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2db70 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2db80 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2db90 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2dba0 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2dbb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2dbc0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2dbd0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2dbe0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2dbf0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2dc00 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2dc10 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2dc20 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2dc30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2dc40 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2dc50 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2dc60 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2dc70 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2dc80 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2dc90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2dca0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2dcb0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2dcc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2dcd0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2dce0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2dcf0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2dd00 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2dd10 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2dd20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2dd30 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2dd40 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2dd50 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2dd60 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2dd70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2dd80 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2dd90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2dda0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ddb0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ddc0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2ddd0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2dde0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2ddf0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2de00 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2de10 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2de20 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2de30 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2de40 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2de50 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2de60 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2de70 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2de80 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2de90 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2dea0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2deb0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2dec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ded0 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2dee0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2def0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2df00 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2df10 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2df20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2df30 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2df40 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2df50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2df60 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2df70 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2df80 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2df90 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2dfa0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2dfb0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2dfc0 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2dfd0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2dfe0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2dff0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2e000 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2e010 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2e020 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2e030 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2e040 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2e050 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2e060 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2e070 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e080 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e090 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2e0a0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e0b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e0c0 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2e0d0 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2e0e0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2e0f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e100 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2e110 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2e120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e130 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2e140 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2e150 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2e160 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2e170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e180 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2e190 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2e1a0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2e1b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2e1c0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2e1d0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2e1e0 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2e1f0 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2e200 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2e210 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2e220 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2e230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6e  * ^The sqlite3_n
2e240 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29  ormalized_sql(P)
2e250 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e260 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2e270 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2e280 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2e290 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51 4c 20   normalized SQL 
2e2a0 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64  text of prepared
2e2b0 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20 20 54   statement P.  T
2e2c0 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63 73 20  he.** semantics 
2e2d0 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c 69 7a  used to normaliz
2e2e0 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e a SQL statemen
2e2f0 74 20 61 72 65 20 75 6e 73 70 65 63 69 66 69 65  t are unspecifie
2e300 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a 2a 2a  d and subject.**
2e310 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41 74 20   to change.  At 
2e320 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 72  a minimum, liter
2e330 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c 20 62  al values will b
2e340 65 20 72 65 70 6c 61 63 65 64 20 77 69 74 68 20  e replaced with 
2e350 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 63  suitable.** plac
2e360 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  eholders..**.** 
2e370 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2e380 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2e390 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2e3a0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2e3b0 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2e3c0 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2e3d0 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2e3e0 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2e3f0 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2e400 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2e410 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2e420 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2e430 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2e440 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2e450 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2e460 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2e470 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2e480 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2e490 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2e4a0 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2e4b0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2e4c0 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2e4d0 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2e4e0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2e4f0 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2e500 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2e510 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2e520 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2e530 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2e540 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2e550 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2e560 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2e570 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2e580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2e590 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2e5a0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2e5b0 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2e5c0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2e5d0 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2e5e0 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2e5f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2e600 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2e610 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2e620 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2e630 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2e640 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2e650 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2e660 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2e670 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  y sqlite3_sql(P)
2e680 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e 6f 72   and sqlite3_nor
2e690 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 0a 2a  malized_sql(P).*
2e6a0 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20 62 79  * are managed by
2e6b0 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72 65 20   SQLite and are 
2e6c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2e6d0 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65  eed when the pre
2e6e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2e6f0 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e  nt is finalized.
2e700 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2e710 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2e720 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2e730 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65  (P), on the othe
2e740 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62  r hand,.** is ob
2e750 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2e760 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
2e770 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20  nd must be free 
2e780 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2e790 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67  on.** by passing
2e7a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
2e7b0 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  free()]..*/.cons
2e7c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2e7d0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2e7e0 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a   *pStmt);.char *
2e7f0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2e800 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2e810 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e 73 74  t *pStmt);.const
2e820 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6e   char *sqlite3_n
2e830 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 73 71  ormalized_sql(sq
2e840 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e850 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e860 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2e870 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2e880 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2e890 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2e8a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e8b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e8c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e8d0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2e8e0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2e8f0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2e900 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2e910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e920 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2e930 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2e940 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2e950 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2e960 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2e970 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2e980 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2e990 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2e9a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2e9b0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2e9c0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2e9d0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2e9e0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2e9f0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2ea00 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2ea10 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2ea20 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2ea30 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2ea40 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2ea50 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2ea60 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2ea70 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2ea80 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2ea90 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2eaa0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2eab0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2eac0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2ead0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2eae0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2eaf0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2eb00 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2eb10 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2eb20 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2eb30 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2eb40 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2eb50 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2eb60 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2eb70 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2eb80 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2eb90 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2eba0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2ebb0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2ebc0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2ebd0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2ebe0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2ebf0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2ec00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2ec10 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2ec20 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2ec30 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2ec40 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2ec50 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2ec60 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2ec70 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2ec80 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2ec90 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2eca0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2ecb0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2ecc0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2ecd0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2ece0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2ecf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2ed00 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2ed10 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2ed20 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2ed30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2ed40 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2ed50 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2ed60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2ed70 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2ed80 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2ed90 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2eda0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2edb0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2edc0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2edd0 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2ede0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2edf0 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2ee00 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2ee10 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2ee20 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2ee30 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2ee40 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2ee50 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2ee60 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2ee70 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2ee80 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2ee90 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2eea0 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2eeb0 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2eec0 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2eed0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2eee0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2eef0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ef00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ef10 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2ef20 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ef30 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2ef40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ef50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ef60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2ef70 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2ef80 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2ef90 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2efa0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2efb0 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2efc0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2efd0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2efe0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2eff0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2f000 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2f010 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2f020 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2f030 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2f040 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2f050 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2f060 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2f070 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2f080 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2f090 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2f0a0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2f0b0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2f0c0 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2f0d0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2f0e0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2f0f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f100 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2f110 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2f120 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2f130 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2f140 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2f150 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2f160 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2f170 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2f180 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2f190 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2f1a0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2f1b0 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2f1c0 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2f1d0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2f1e0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2f1f0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2f200 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2f210 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2f220 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2f230 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2f240 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2f250 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2f260 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2f270 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2f280 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2f290 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2f2a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2f2b0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2f2c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f2d0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2f2e0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2f2f0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2f300 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2f310 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2f320 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f330 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2f340 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2f350 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f360 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2f370 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2f380 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2f390 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2f3a0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2f3b0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2f3c0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2f3d0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2f3e0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2f3f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f400 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2f410 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2f420 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2f430 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2f440 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2f450 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2f460 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2f470 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2f480 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2f490 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2f4a0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2f4b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f4c0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2f4d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2f4e0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2f4f0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2f500 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2f510 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2f520 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2f530 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2f540 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2f550 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2f560 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2f570 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2f580 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f590 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2f5a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f5b0 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2f5c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2f5d0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2f5e0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2f5f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2f600 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2f610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2f620 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2f630 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2f640 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2f650 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2f660 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2f670 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2f680 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2f690 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2f6a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2f6b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2f6c0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2f6d0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2f6e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2f6f0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2f700 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2f710 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2f720 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2f730 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2f740 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2f750 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2f760 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2f770 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2f780 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2f790 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2f7a0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2f7b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2f7c0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2f7d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2f7e0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2f7f0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2f800 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2f810 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2f820 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2f830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2f840 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2f850 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2f860 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2f870 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2f880 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2f890 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2f8a0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2f8b0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2f8c0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2f8d0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2f8e0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2f8f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2f900 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2f910 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2f920 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2f930 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f940 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f950 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2f960 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2f970 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2f980 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f990 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2f9a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2f9b0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2f9c0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2f9d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f9e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2f9f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fa00 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2fa10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2fa20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fa30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2fa40 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61  y only be used a
2fa50 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  s arguments.** t
2fa60 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2fa70 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c  t_value()], [sql
2fa80 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2fa90 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2faa0 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
2fab0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2fac0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2fad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2fae0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2faf0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2fb00 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2fb10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fb20 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2fb30 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2fb40 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61  value sqlite3_va
2fb50 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2fb60 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2fb70 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2fb80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2fb90 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2fba0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2fbb0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2fbc0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2fbd0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2fbe0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2fbf0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2fc00 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2fc10 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2fc20 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2fc30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2fc40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2fc50 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2fc60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fc70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2fc80 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2fc90 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2fca0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2fcb0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2fcc0 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2fcd0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2fce0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2fcf0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2fd00 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2fd10 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2fd20 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2fd30 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2fd40 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2fd50 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2fd60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2fd70 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2fd80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2fd90 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2fda0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2fdb0 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2fdc0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2fdd0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2fde0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2fdf0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2fe00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2fe10 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2fe20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2fe30 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2fe40 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2fe50 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2fe60 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
2fe70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2fe80 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
2fe90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
2fea0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
2feb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2fec0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
2fed0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
2fee0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
2fef0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
2ff00 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
2ff10 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
2ff20 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
2ff30 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2ff40 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
2ff50 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
2ff60 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
2ff70 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
2ff80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
2ff90 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
2ffa0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
2ffb0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
2ffc0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
2ffd0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
2ffe0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
2fff0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
30000 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
30010 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
30020 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
30030 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
30040 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
30050 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
30060 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
30070 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
30080 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
30090 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
300a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
300b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
300c0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
300d0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
300e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
300f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
30100 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
30110 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
30120 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
30130 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
30140 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
30150 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
30160 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
30170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
30180 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
30190 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
301a0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
301b0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
301c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
301d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
301e0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
301f0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
30200 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
30210 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
30220 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
30230 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
30240 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
30250 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
30260 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
30270 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
30280 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
30290 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
302a0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
302b0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
302c0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
302d0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
302e0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
302f0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
30300 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
30310 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
30320 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
30330 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
30340 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
30350 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
30360 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
30370 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
30380 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
30390 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
303a0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
303b0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
303c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
303d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
303e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
303f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
30400 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
30410 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
30420 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
30430 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
30440 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
30450 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
30460 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
30470 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
30480 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
30490 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
304a0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
304b0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
304c0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
304d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
304e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
304f0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
30500 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
30510 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
30520 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
30530 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
30540 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
30550 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
30560 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
30570 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
30580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30590 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
305a0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
305b0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
305c0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
305d0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
305e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
305f0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
30600 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
30610 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
30620 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30630 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
30640 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
30650 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
30660 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
30670 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
30680 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
30690 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
306a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
306b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
306c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
306d0 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
306e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
306f0 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
30700 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
30710 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
30720 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
30730 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
30740 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
30750 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
30760 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
30770 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
30780 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
30790 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
307a0 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
307b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
307c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
307d0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
307e0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
307f0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
30800 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
30810 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
30820 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
30830 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
30840 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
30850 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
30860 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30870 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
30880 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
30890 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
308a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
308b0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
308c0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
308d0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
308e0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
308f0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
30900 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
30910 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
30920 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
30930 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
30940 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
30950 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
30960 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
30970 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
30980 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
30990 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
309a0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
309b0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
309c0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
309d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
309e0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
309f0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
30a00 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
30a10 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
30a20 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
30a30 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
30a40 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
30a50 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
30a60 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
30a70 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
30a80 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
30a90 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
30aa0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
30ab0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
30ac0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
30ad0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
30ae0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
30af0 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
30b00 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
30b10 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
30b20 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
30b30 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
30b40 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
30b50 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
30b60 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
30b70 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
30b80 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
30b90 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
30ba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
30bb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
30bc0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
30bd0 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
30be0 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
30bf0 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
30c00 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
30c10 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
30c20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
30c30 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
30c40 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
30c50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
30c60 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
30c70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30c80 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
30c90 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
30ca0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
30cb0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
30cc0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
30cd0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
30ce0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
30cf0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
30d00 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
30d10 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
30d20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
30d30 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
30d40 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
30d50 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
30d60 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
30d70 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
30d80 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
30d90 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
30da0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
30db0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
30dc0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
30dd0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
30de0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
30df0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
30e00 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
30e10 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
30e20 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  LOB..**.** ^The 
30e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
30e40 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20  nter(S,I,P,T,D) 
30e50 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74  routine causes t
30e60 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65  he I-th paramete
30e70 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65  r in.** [prepare
30e80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74  d statement] S t
30e90 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61  o have an SQL va
30ea0 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74  lue of NULL, but
30eb0 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61   to also be.** a
30ec0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
30ed0 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20  he pointer P of 
30ee0 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65  type T.  ^D is e
30ef0 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
30f00 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69  nter or.** a poi
30f10 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
30f20 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ctor function fo
30f30 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c  r P. ^SQLite wil
30f40 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20  l invoke the.** 
30f50 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
30f60 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
30f70 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74  ent of P when it
30f80 20 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69   is finished usi
30f90 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20  ng.** P.  The T 
30fa0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
30fb0 20 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72   be a static str
30fc0 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20  ing, preferably 
30fd0 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65  a string.** lite
30fe0 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33  ral. The sqlite3
30ff0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20  _bind_pointer() 
31000 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20  routine is part 
31010 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74  of the.** [point
31020 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72  er passing inter
31030 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20  face] added for 
31040 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a  SQLite 3.20.0..*
31050 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
31060 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
31070 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
31080 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
31090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
310a0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
310b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
310c0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
310d0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
310e0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
310f0 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
31100 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
31110 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
31120 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
31130 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
31140 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
31150 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
31160 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
31170 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
31180 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
31190 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
311a0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
311b0 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
311c0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
311d0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
311e0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
311f0 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
31200 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
31210 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31220 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
31230 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
31240 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
31250 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
31260 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
31270 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
31280 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
31290 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
312a0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
312b0 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
312c0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
312d0 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
312e0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
312f0 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
31300 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
31310 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
31320 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
31330 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
31340 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
31350 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
31360 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
31370 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
31380 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
31390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
313a0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
313b0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
313c0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
313d0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
313e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
313f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31410 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
31420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31430 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
31440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
31450 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
31460 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
31470 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
31480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31490 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
314a0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
314b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
314c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
314d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
314e0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
314f0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
31500 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31510 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
31520 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
31530 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
31540 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31550 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
31560 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
31570 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
31580 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
31590 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
315a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
315b0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
315c0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
315d0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
315e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
315f0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
31600 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
31610 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
31620 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
31630 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
31640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31650 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
31660 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
31670 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
31680 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
31690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
316a0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
316b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
316c0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
316d0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
316e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
316f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
31700 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
31710 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
31720 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
31730 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31740 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
31750 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
31760 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
31770 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  r(sqlite3_stmt*,
31780 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e   int, void*, con
31790 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29  st char*,void(*)
317a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
317b0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
317c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
317d0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
317e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
317f0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
31800 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
31810 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
31820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31830 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
31840 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
31850 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31860 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
31870 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
31880 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
31890 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
318a0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
318b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
318c0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
318d0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
318e0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
318f0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
31900 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
31910 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
31920 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
31930 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
31940 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
31950 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
31960 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
31970 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
31980 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
31990 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
319a0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
319b0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
319c0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
319d0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
319e0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
319f0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
31a00 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
31a10 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
31a20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
31a30 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
31a40 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
31a50 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
31a60 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
31a70 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
31a80 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
31a90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
31aa0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
31ab0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
31ac0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
31ad0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
31ae0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
31af0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31b00 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
31b10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
31b20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
31b30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31b50 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
31b60 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
31b70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31b80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
31b90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31ba0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
31bb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
31bc0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
31bd0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
31be0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
31bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31c00 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
31c10 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
31c20 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
31c30 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
31c40 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
31c50 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
31c60 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
31c70 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
31c80 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
31c90 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
31ca0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
31cb0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
31cc0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
31cd0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
31ce0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
31cf0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
31d00 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
31d10 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
31d20 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
31d30 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
31d40 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
31d50 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
31d60 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
31d70 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
31d80 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
31d90 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
31da0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
31db0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
31dc0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
31dd0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
31de0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
31df0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
31e00 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
31e10 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
31e20 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
31e30 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
31e40 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
31e50 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
31e60 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
31e70 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
31e80 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
31e90 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
31ea0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
31eb0 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b  epare16()],.** [
31ec0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31ed0 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  6_v2()], or [sql
31ee0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31ef0 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  3()]..**.** See 
31f00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
31f10 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
31f20 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
31f30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
31f40 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
31f50 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
31f60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
31f70 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
31f80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
31f90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
31fa0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
31fb0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
31fc0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
31fd0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
31fe0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
31ff0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32000 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
32010 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
32020 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
32030 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
32040 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
32050 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
32060 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
32070 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
32080 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
32090 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
320a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
320b0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
320c0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
320d0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
320e0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
320f0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
32100 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
32110 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
32120 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
32130 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
32140 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
32150 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
32160 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
32170 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
32180 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32190 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
321a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
321b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
321c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
321d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
321e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
321f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
32200 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
32210 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
32220 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32240 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
32250 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
32260 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
32270 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
32280 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
32290 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
322a0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
322b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
322c0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
322d0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
322e0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
322f0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
32300 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
32310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32320 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
32330 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32340 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
32350 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
32360 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
32370 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
32380 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
32390 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
323a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
323b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
323c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
323d0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
323e0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
323f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32400 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
32410 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
32420 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
32430 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
32440 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
32450 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20  statement]. ^If 
32460 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
32470 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61  urns 0, that mea
32480 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  ns the .** [prep
32490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
324a0 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20  returns no data 
324b0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
324c0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48  [UPDATE])..** ^H
324d0 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63  owever, just bec
324e0 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ause this routin
324f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  e returns a posi
32500 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73  tive number does
32510 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61   not.** mean tha
32520 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f  t one or more ro
32530 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20  ws of data will 
32540 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41  be returned.  ^A
32550 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
32560 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  t.** will always
32570 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65   have a positive
32580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32590 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65  count() but depe
325a0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20  nding on the.** 
325b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
325c0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65  straints and the
325d0 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20   table content, 
325e0 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  it might return 
325f0 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53  no rows..**.** S
32600 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
32610 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
32620 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
32630 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
32640 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
32650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32660 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
32670 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
32680 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32690 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
326a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
326b0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
326c0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
326d0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
326e0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
326f0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
32700 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
32710 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32720 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
32730 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
32740 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
32750 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
32760 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
32770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
32780 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
32790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
327a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
327b0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
327c0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
327d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
327e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
327f0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
32800 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
32810 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
32820 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
32830 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
32840 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
32850 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
32860 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
32870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
32880 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
32890 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
328a0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
328b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
328c0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
328d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
328e0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
328f0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
32900 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
32910 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
32920 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
32930 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
32940 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
32950 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
32960 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
32970 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
32980 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
32990 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
329a0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
329b0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
329c0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
329d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
329e0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
329f0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
32a00 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
32a10 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
32a20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
32a30 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
32a40 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
32a50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
32a60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
32a70 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
32a80 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
32a90 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
32aa0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
32ab0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
32ac0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
32ad0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
32ae0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
32af0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
32b00 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
32b10 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
32b20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
32b30 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
32b40 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
32b50 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
32b60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32b70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
32b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32b90 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
32ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
32bb0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
32bc0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
32bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
32be0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
32bf0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
32c00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32c10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
32c20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
32c30 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
32c40 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
32c50 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
32c60 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
32c70 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
32c80 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
32c90 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
32ca0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
32cb0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
32cc0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
32cd0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
32ce0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
32cf0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
32d00 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
32d10 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
32d20 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
32d30 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
32d40 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
32d50 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
32d60 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
32d70 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
32d80 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
32d90 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
32da0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
32db0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
32dc0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
32dd0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
32de0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
32df0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
32e00 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
32e10 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
32e20 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
32e30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
32e40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
32e50 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
32e60 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
32e70 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
32e80 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
32e90 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
32ea0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
32eb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
32ec0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
32ed0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
32ee0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
32ef0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
32f00 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
32f10 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
32f20 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
32f30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
32f40 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
32f50 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
32f60 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
32f70 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
32f80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32f90 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
32fa0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
32fb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
32fc0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
32fd0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
32fe0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
32ff0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
33000 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
33010 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
33020 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
33030 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
33040 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
33050 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
33060 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
33070 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
33080 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
33090 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
330a0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
330b0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
330c0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
330d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
330e0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
330f0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
33100 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
33110 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
33120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
33130 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
33140 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
33150 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
33160 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
33170 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
33180 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
33190 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
331a0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
331b0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
331c0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
331d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
331e0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
331f0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
33200 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
33210 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
33220 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
33230 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
33240 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
33250 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
33260 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
33270 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
33280 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
33290 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
332a0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
332b0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
332c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
332d0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
332e0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
332f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
33300 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
33310 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
33320 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
33330 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
33340 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
33350 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
33360 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
33370 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
33380 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
33390 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
333a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
333b0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
333c0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
333d0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
333e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
333f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33400 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
33410 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
33420 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
33430 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33440 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
33450 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
33460 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
33470 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
33480 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
33490 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
334a0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
334b0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
334c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
334d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
334e0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
334f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
33500 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
33510 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33520 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
33530 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
33540 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
33550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
33560 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
33570 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
33580 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33590 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
335a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
335b0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
335c0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
335d0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
335e0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
335f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33600 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
33610 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
33620 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
33630 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
33640 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
33650 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
33660 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
33670 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
33680 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
33690 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
336a0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
336b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
336c0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
336d0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
336e0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
336f0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
33700 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
33710 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
33720 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
33730 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
33740 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
33750 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
33760 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
33770 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
33780 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
33790 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
337a0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
337b0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
337c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
337d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
337e0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
337f0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
33800 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
33810 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
33820 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
33830 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
33840 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
33850 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
33860 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
33870 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
33880 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
33890 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
338a0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
338b0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
338c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
338d0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
338e0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
338f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
33900 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
33910 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
33920 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
33930 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
33940 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
33950 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
33960 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
33970 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
33980 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
33990 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
339a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
339b0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
339c0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
339d0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
339e0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
339f0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
33a00 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
33a10 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
33a20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
33a30 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
33a40 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
33a50 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
33a60 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
33a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
33a80 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
33a90 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
33aa0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
33ab0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
33ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
33ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33ae0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
33af0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
33b00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33b10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
33b20 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
33b30 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
33b40 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
33b50 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69   any of.** [sqli
33b60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
33b70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
33b80 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
33b90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
33ba0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
33bb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
33bc0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
33bd0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
33be0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
33bf0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
33c00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33c10 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
33c20 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
33c30 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
33c40 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
33c50 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
33c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
33c70 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
33c80 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
33c90 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
33ca0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
33cb0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
33cc0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
33cd0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
33ce0 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61  wer "vX" interfa
33cf0 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ces.** [sqlite3_
33d00 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
33d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d20 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33d30 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c  prepare16_v3()],
33d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
33d50 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
33d60 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
33d70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
33d80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
33d90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33da0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
33db0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
33dc0 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66   new "vX" interf
33dd0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
33de0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
33df0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
33e00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
33e10 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
33e20 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
33e30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
33e40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
33e50 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
33e60 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
33e70 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
33e80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
33e90 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
33ea0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
33eb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
33ec0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
33ed0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
33ee0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
33ef0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
33f00 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
33f10 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
33f20 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
33f30 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
33f40 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
33f50 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33f60 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
33f70 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
33f80 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
33f90 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
33fa0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
33fb0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
33fc0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
33fd0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
33fe0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
33ff0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
34000 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
34010 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
34020 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
34030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
34040 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
34050 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
34060 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
34070 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
34080 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
34090 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
340a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
340b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
340c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
340d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
340e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
340f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
34100 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
34110 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
34120 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
34130 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
34140 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
34150 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
34160 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
34170 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
34180 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
34190 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
341a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
341b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
341c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
341d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
341e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
341f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
34200 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
34210 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
34220 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
34230 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
34240 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
34250 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
34260 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
34270 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
34280 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
34290 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
342a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
342b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
342c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
342d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
342e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
342f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
34300 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
34310 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
34320 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
34330 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
34340 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
34350 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
34360 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
34370 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
34380 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
34390 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
343a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
343b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
343c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
343d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
343e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
343f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
34400 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
34410 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
34420 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
34430 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
34440 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
34450 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
34460 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
34470 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
34480 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
34490 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
344a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
344b0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
344c0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
344d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
344e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
344f0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
34500 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
34510 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
34520 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
34530 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
34540 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
34550 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
34560 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
34570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
34580 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
34590 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
345a0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
345b0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
345c0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
345d0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
345e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
345f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
34600 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
34610 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
34620 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
34630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
34640 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
34650 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
34660 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
34670 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
34680 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
34690 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
346a0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
346b0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
346c0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
346d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
346e0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
346f0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
34700 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
34710 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
34720 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
34730 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
34740 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
34750 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
34760 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
34770 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
34780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
34790 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
347a0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
347b0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
347c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
347d0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
347e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
347f0 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
34800 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
34810 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
34820 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
34830 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
34840 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
34850 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
34860 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
34870 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
34880 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
34890 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
348a0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
348b0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
348c0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
348d0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
348e0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
348f0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
34900 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
34910 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
34920 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
34930 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
34940 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
34950 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
34960 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
34970 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
34980 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
34990 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
349a0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
349b0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
349c0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
349d0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
349e0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
349f0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
34a00 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
34a10 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
34a20 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
34a30 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
34a40 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
34a50 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
34a60 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
34a70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
34a80 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
34a90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
34aa0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
34ab0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
34ac0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
34ad0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
34ae0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
34af0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
34b00 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
34b10 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
34b20 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
34b30 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
34b40 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
34b50 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
34b60 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
34b70 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
34b80 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
34b90 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
34ba0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
34bb0 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  pare_v2()].** or
34bc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34bd0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  e16_v2()] or [sq
34be0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
34bf0 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v3()] instead.**
34c00 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
34c10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
34c20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34c30 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
34c40 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
34c50 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
34c60 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
34c70 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
34c80 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
34c90 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
34ca0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58  e use of the "vX
34cb0 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  " interfaces is 
34cc0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
34cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
34ce0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
34cf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34d00 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
34d10 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
34d20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
34d30 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
34d50 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
34d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
34d70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
34d80 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
34d90 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
34da0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
34db0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34dc0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
34dd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34de0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
34df0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
34e00 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
34e10 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
34e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34e30 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
34e40 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
34e50 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
34e60 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
34e70 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
34e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34e90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
34ea0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
34eb0 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
34ec0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
34ed0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
34ee0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
34ef0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
34f00 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
34f10 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34f20 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
34f30 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
34f40 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
34f50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
34f60 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
34f70 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
34f80 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
34f90 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
34fa0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
34fb0 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
34fc0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
34fd0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
34fe0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
34ff0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
35000 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
35010 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
35020 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
35030 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
35040 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
35050 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
35060 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
35070 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
35080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
35090 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
350a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
350b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
350c0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
350d0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
350e0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
350f0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
35100 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
35110 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
35120 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
35130 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
35140 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
35150 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
35160 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
35170 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
35180 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
35190 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
351a0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
351b0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
351c0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
351d0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
351e0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
351f0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
35200 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
35210 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
35220 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
35230 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
35240 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
35250 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
35260 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
35270 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
35280 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
35290 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
352a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
352b0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
352c0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
352d0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
352e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
352f0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
35300 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
35310 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
35320 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
35330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
35340 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
35350 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
35360 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
35370 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
35380 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
35390 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
353a0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
353b0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
353c0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
353d0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
353e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
353f0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
35400 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
35410 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
35420 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f  ** <b>Summary:</
35430 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  b>.** <blockquot
35440 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  e><table border=
35450 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20  0 cellpadding=0 
35460 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a  cellspacing=0>.*
35470 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
35480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
35490 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
354a0 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a  d>BLOB result.**
354b0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
354c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
354d0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
354e0 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a  td>REAL result.*
354f0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
35500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c  ite3_column_int<
35510 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
35520 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >32-bit INTEGER 
35530 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
35540 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
35550 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64  umn_int64</b><td
35560 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69  >&rarr;<td>64-bi
35570 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
35580 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
355a0 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  xt</b><td>&rarr;
355b0 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72  <td>UTF-8 TEXT r
355c0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
355d0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
355e0 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64  mn_text16</b><td
355f0 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31  >&rarr;<td>UTF-1
35600 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  6 TEXT result.**
35610 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
35620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35630 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
35640 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20  d>The result as 
35650 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  an .** [sqlite3_
35660 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65  value|unprotecte
35670 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35680 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e   object..** <tr>
35690 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
356a0 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a  bsp;<td>&nbsp;.*
356b0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
356c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
356d0 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  s</b><td>&rarr;<
356e0 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f  td>Size of a BLO
356f0 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20  B.** or a UTF-8 
35700 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62  TEXT result in b
35710 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
35720 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
35730 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26  n_bytes16&nbsp;&
35740 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64  nbsp;</b>.** <td
35750 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62  >&rarr;&nbsp;&nb
35760 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55  sp;<td>Size of U
35770 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e  TF-16.** TEXT in
35780 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
35790 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
357a0 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e  umn_type</b><td>
357b0 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c  &rarr;<td>Defaul
357c0 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66  t.** datatype of
357d0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c   the result.** <
357e0 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75  /table></blockqu
357f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65  ote>.**.** <b>De
35800 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  tails:</b>.**.**
35810 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
35820 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
35830 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
35840 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
35850 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
35860 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
35870 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
35880 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
35890 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
358a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
358b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
358c0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
358d0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
358e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
358f0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
35900 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
35910 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
35920 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
35930 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
35940 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
35950 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
35960 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
35970 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
35980 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
35990 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
359a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
359b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
359c0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
359d0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
359e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
359f0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
35a00 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
35a10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
35a20 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
35a30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
35a40 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
35a50 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
35a60 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
35a70 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
35a80 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
35a90 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
35aa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
35ab0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
35ac0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
35ad0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
35ae0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
35af0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
35b00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
35b10 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
35b20 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
35b30 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
35b40 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
35b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35b60 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
35b70 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
35b80 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
35b90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
35ba0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
35bb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
35bc0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
35bd0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
35be0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
35bf0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
35c00 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
35c10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
35c20 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
35c30 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
35c40 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
35c50 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
35c60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35c70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
35c80 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
35c90 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
35ca0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
35cb0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
35cc0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
35cd0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
35ce0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
35cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
35d00 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
35d10 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20  erfaces (_blob, 
35d20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f  _double, _int, _
35d30 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e  int64, _text, an
35d40 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61  d _text16).** ea
35d50 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61  ch return the va
35d60 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  lue of a result 
35d70 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63  column in a spec
35d80 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74  ific data format
35d90 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73  .  If.** the res
35da0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f  ult column is no
35db0 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74  t initially in t
35dc0 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72  he requested for
35dd0 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  mat (for example
35de0 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72  ,.** if the quer
35df0 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  y returns an int
35e00 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c  eger but the sql
35e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35e20 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
35e30 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  is used to extra
35e40 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68  ct the value) th
35e50 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  en an automatic 
35e60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
35e70 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
35e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35e90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
35ea0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
35eb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
35ec0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
35ed0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
35ee0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
35ef0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
35f00 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
35f10 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
35f20 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
35f30 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
35f40 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
35f50 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
35f60 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
35f70 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a  SQLITE_NULL]..**
35f80 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
35f90 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  e of sqlite3_col
35fa0 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62  umn_type() can b
35fb0 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65  e used to decide
35fc0 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65   which.** of the
35fd0 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
35fe0 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75  face should be u
35ff0 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
36000 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  he column value.
36010 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
36020 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
36030 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
36040 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
36050 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f  ul if no.** auto
36060 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
36070 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
36080 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c  rred for the val
36090 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20  ue in question. 
360a0 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70   .** After a typ
360b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68  e conversion, th
360c0 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c  e result of call
360d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ing sqlite3_colu
360e0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20  mn_type().** is 
360f0 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67  undefined, thoug
36100 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74  h harmless.  Fut
36110 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
36120 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
36130 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
36140 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
36150 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
36160 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
36170 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
36180 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
36190 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45  s a BLOB or a TE
361a0 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  XT string, then 
361b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
361c0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72  mn_bytes().** or
361d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
361e0 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66  bytes16() interf
361f0 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  aces can be used
36200 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
36210 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61  e size.** of tha
36220 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
36230 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
36240 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
36250 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
36260 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
36270 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36280 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
36290 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
362a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
362b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
362c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
362d0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
362e0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
362f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36300 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
36310 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
36320 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
36330 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
36340 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
36350 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
36360 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
36370 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
36380 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
36390 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
363a0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
363b0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
363c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
363d0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
363e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
363f0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
36400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
36410 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
36420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36430 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
36440 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
36450 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
36460 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
36470 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
36480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36490 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
364a0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
364b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
364c0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
364d0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
364e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
364f0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
36500 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36510 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
36520 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
36530 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
36540 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
36550 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
36560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
36570 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
36580 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
36590 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
365a0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
365b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
365c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
365d0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
365e0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
365f0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
36600 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
36610 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
36620 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
36630 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
36640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36650 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
36660 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
36670 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
36680 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
36690 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
366a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
366b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
366c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
366d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
366e0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
366f0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
36700 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
36710 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
36720 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
36730 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
36740 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
36750 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
36760 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
36770 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
36780 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
36790 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
367a0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
367b0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
367c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
367d0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
367e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
367f0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
36800 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
36810 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
36820 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
36830 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
36840 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
36850 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
36860 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
36870 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
36880 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
36890 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
368a0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
368b0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
368c0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
368d0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
368e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
368f0 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
36900 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
36910 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
36920 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36930 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
36940 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
36950 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
36960 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
36970 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
36980 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36990 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
369a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
369b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
369c0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
369d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
369e0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
369f0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
36a00 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
36a10 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
36a20 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
36a30 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
36a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36a50 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
36a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
36a70 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
36a80 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
36a90 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  safe..** Hence, 
36aa0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
36ab0 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  mn_value() inter
36ac0 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61  face.** is norma
36ad0 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20  lly only useful 
36ae0 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65  within the imple
36af0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a  mentation of .**
36b00 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
36b10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
36b20 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c  ons] or [virtual
36b30 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69   tables], not wi
36b40 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  thin.** top-leve
36b50 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  l application co
36b60 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  de..**.** The th
36b70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
36b80 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
36b90 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65  ert the datatype
36ba0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a   of the result..
36bb0 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ** ^For example,
36bc0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
36bd0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
36be0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
36bf0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
36c00 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
36c10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
36c20 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
36c30 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
36c40 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
36c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
36c60 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
36c70 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
36c80 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
36c90 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
36ca0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
36cb0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
36cc0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
36cd0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
36ce0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
36cf0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
36d00 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
36d10 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
36d20 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
36d30 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
36d40 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
36d50 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
36d60 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
36d70 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
36d80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
36d90 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
36da0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
36db0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
36dc0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
36dd0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
36de0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
36df0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
36e00 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
36e10 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
36e20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
36e30 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
36e40 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
36e50 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
36e60 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
36e70 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
36e80 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
36e90 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
36ea0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
36eb0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
36ec0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
36ed0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
36ee0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
36ef0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
36f00 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
36f10 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
36f20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
36f30 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
36f40 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
36f50 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
36f60 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
36f70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
36f80 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
36f90 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
36fa0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
36fb0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
36fc0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
36fd0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
36fe0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
36ff0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
37000 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
37010 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
37020 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
37030 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
37040 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
37050 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
37060 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
37070 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
37080 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
37090 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
370a0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
370b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
370c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
370d0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
370e0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
370f0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
37100 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
37110 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
37120 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
37130 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
37140 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
37150 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
37160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37170 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
37180 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
37190 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
371a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
371b0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
371c0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
371d0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
371e0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
371f0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
37200 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
37210 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
37220 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
37230 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
37240 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
37250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37260 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
37270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37280 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
37290 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
372a0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
372b0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
372c0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
372d0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
372e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
372f0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
37300 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
37310 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
37320 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
37330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37340 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
37350 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
37360 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
37370 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
37380 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
37390 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
373a0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
373b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
373c0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
373d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
373e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
373f0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
37400 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
37410 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
37420 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
37430 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
37440 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
37450 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
37460 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
37470 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
37480 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
37490 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
374a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
374b0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
374c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
374d0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
374e0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
374f0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
37500 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
37510 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
37520 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
37530 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
37540 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
37550 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
37560 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
37570 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
37580 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
37590 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
375a0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
375b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
375c0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
375d0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
375e0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
375f0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
37600 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
37610 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
37620 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
37630 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
37640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37650 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
37660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37670 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
37680 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
37690 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
376a0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
376b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
376c0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
376d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
376e0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
376f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
37700 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
37710 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
37720 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
37730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37740 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
37750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37760 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
37770 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
37780 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
37790 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
377a0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
377b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
377c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
377d0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
377e0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
377f0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
37800 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
37810 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
37820 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
37830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
37840 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
37850 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
37860 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
37870 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
37880 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
37890 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
378a0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
378b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
378c0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
378d0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
378e0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
378f0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
37900 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
37910 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
37920 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
37930 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
37940 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
37950 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
37960 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
37970 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
37980 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
37990 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
379a0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
379b0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
379c0 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73  lly.  Do not pas
379d0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
379e0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
379f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37a00 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
37a10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
37a20 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
37a30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
37a40 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
37a50 73 20 74 68 65 20 69 6e 70 75 74 20 70 61 72 61  s the input para
37a60 6d 65 74 65 72 73 20 61 72 65 20 63 6f 72 72 65  meters are corre
37a70 63 74 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ct, these routin
37a80 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a 2a 20  es will only.** 
37a90 66 61 69 6c 20 69 66 20 61 6e 20 6f 75 74 2d 6f  fail if an out-o
37aa0 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f  f-memory error o
37ab0 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 66  ccurs during a f
37ac0 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73 69 6f 6e  ormat conversion
37ad0 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20 66 6f  ..** Only the fo
37ae0 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65 74 20 6f  llowing subset o
37af0 66 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  f interfaces are
37b00 20 73 75 62 6a 65 63 74 20 74 6f 20 6f 75 74 2d   subject to out-
37b10 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65 72 72  of-memory.** err
37b20 6f 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ors:.**.** <ul>.
37b30 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
37b40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a 2a 2a  column_blob().**
37b50 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
37b60 6c 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a 20 3c  lumn_text().** <
37b70 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  li> sqlite3_colu
37b80 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 3c  mn_text16().** <
37b90 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  li> sqlite3_colu
37ba0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 3c 6c  mn_bytes().** <l
37bb0 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
37bc0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 3c  n_bytes16().** <
37bd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  /ul>.**.** If an
37be0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65   out-of-memory e
37bf0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 74 68 65  rror occurs, the
37c00 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
37c10 75 65 20 66 72 6f 6d 20 74 68 65 73 65 0a 2a 2a  ue from these.**
37c20 20 72 6f 75 74 69 6e 65 73 20 69 73 20 74 68 65   routines is the
37c30 20 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 20   same as if the 
37c40 63 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e 74 61  column had conta
37c50 69 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ined an SQL NULL
37c60 20 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c 69 64   value..** Valid
37c70 20 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75 72 6e   SQL NULL return
37c80 73 20 63 61 6e 20 62 65 20 64 69 73 74 69 6e 67  s can be disting
37c90 75 69 73 68 65 64 20 66 72 6f 6d 20 6f 75 74 2d  uished from out-
37ca0 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 73  of-memory errors
37cb0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
37cc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  the [sqlite3_err
37cd0 63 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69 61 74  code()] immediat
37ce0 65 6c 79 20 61 66 74 65 72 20 74 68 65 20 73 75  ely after the su
37cf0 73 70 65 63 74 0a 2a 2a 20 72 65 74 75 72 6e 20  spect.** return 
37d00 76 61 6c 75 65 20 69 73 20 6f 62 74 61 69 6e 65  value is obtaine
37d10 64 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  d and before any
37d20 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
37d30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
37d40 6c 6c 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  lled on the same
37d50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37d60 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ction]..*/.const
37d70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
37d80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
37d90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
37da0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
37db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
37dc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
37dd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
37de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
37df0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
37e00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
37e10 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
37e20 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
37e30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
37e40 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
37e50 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
37e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37e70 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
37e80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
37e90 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
37ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
37eb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
37ec0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
37ed0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
37ee0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
37ef0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
37f00 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
37f10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
37f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
37f30 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
37f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37f50 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
37f60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
37f70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
37f80 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
37f90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
37fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37fb0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
37fc0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
37fd0 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43  bject.** DESTRUC
37fe0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
37ff0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
38000 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
38010 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
38020 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
38030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38040 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
38050 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
38060 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
38070 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
38080 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
38090 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
380a0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
380b0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
380c0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
380d0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
380e0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
380f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
38100 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
38110 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
38120 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
38130 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
38140 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
38150 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
38160 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
38170 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
38180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38190 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
381a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
381b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
381c0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
381d0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
381e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
381f0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
38200 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
38210 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
38220 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
38230 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
38240 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
38250 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
38260 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
38270 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
38280 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
38290 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
382a0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
382b0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
382c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
382d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
382e0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
382f0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
38300 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
38310 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
38320 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
38330 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
38340 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
38350 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
38360 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
38370 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
38380 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
38390 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
383a0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
383b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
383c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
383d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
383e0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
383f0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
38400 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
38410 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
38420 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
38430 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
38440 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
38450 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
38460 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
38470 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
38480 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
38490 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
384a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
384b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
384c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
384d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
384e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
384f0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
38500 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
38510 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
38520 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
38530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
38540 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
38550 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
38560 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
38570 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
38580 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
38590 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
385a0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
385b0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
385c0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
385d0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
385e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
385f0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
38600 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
38610 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
38620 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
38630 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
38640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
38650 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
38660 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
38670 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
38680 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
38690 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
386a0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
386b0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
386c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
386d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
386e0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
386f0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
38700 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
38710 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
38720 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
38730 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
38740 74 65