SQLite Android Bindings

Hex Artifact Content
Login

Artifact e59fbb91b7624917652adbc966d2c95f8a1c1130:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 33 2e 32 32 2e 30 22 0a 23 64 65      "3.22.0".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 32 30  ION_NUMBER 30220
1230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 38 2d 30 31 2d 32 32 20 31 38 3a   "2018-01-22 18:
1260: 34 35 3a 35 37 20 30 63 35 35 64 31 37 39 37 33  45:57 0c55d17973
1270: 33 62 34 36 64 38 64 30 62 61 34 64 38 38 65 30  3b46d8d0ba4d88e0
1280: 31 61 32 35 65 31 30 36 37 37 30 34 36 65 65 33  1a25e10677046ee3
1290: 64 61 31 64 35 62 31 35 38 31 65 38 36 37 32 36  da1d5b1581e86726
12a0: 66 32 31 37 31 64 22 0a 0a 2f 2a 0a 2a 2a 20 43  f2171d"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1e80: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1e90: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ea0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1eb0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1ec0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ed0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1ee0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1ef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1f00: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1f10: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1f20: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1f30: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1f40: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1f50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f60: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1f70: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1f80: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1f90: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1fa0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1fb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1fc0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1fd0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1fe0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1ff0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
2000: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
2010: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
2020: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
2030: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
2040: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
2050: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
2060: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
2070: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
2080: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
2090: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
20a0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
20b0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
20c0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
20d0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
20e0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
20f0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
2100: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
2110: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
2120: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
2130: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2140: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2150: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2160: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2170: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2180: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2190: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
21a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
21b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
21c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
21d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
21e0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
21f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2200: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2210: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2220: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2230: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2240: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2250: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2260: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2270: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2290: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
22a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
22b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
22c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
22d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
22f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2300: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2310: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2320: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2330: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2340: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2350: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2360: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2370: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2390: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
23a0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
23b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
23c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
23d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
23e0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
23f0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2400: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2410: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2430: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2440: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2450: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2460: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2470: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2480: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2490: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
24a0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
24b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
24c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
24d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
24f0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2500: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2510: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2520: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2530: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2540: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2550: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2560: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2570: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2580: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2590: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25b0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25c0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
25d0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
25e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
25f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2600: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2610: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2620: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2630: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2640: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2650: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2660: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2670: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2680: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2690: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
26a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
26b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
26c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2710: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2720: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2730: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2750: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2760: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2770: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2780: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2790: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
27a0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
27b0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
27d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
27e0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
27f0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2800: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2810: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2820: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2830: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2840: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2850: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2860: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2870: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2880: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2890: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
28a0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
28b0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
28c0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
28d0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
28e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
28f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2900: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2910: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2920: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2940: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2950: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2960: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2970: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2980: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2990: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
29a0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
29b0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
29c0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
29d0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
29e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
29f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2a00: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2a10: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2a20: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2a30: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2a40: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2a50: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2a60: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2a70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2a80: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2a90: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2aa0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2ac0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2ad0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2af0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2b00: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2b30: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2b40: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2b50: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2b60: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2b70: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2b80: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2ba0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2bb0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2bc0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2bd0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2be0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2bf0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2c00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2c30: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2c40: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2c50: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2c60: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2c70: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2c90: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2cb0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2cc0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2cd0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ce0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2cf0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2d00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2d10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2d20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2d30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2d40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2d50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2d60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2d70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2d80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2d90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2da0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2db0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2dc0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2dd0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2de0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2df0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2e00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2e10: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2e20: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2e40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2e50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e60: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2e70: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2e80: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e90: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ea0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2eb0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ec0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2ed0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2ee0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2ef0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2f00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f10: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2f20: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2f30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2f40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2f50: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2f60: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2f70: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2f80: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2f90: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2fb0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2fc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2fd0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2fe0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2ff0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
3000: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
3010: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
3020: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
3030: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
3040: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
3050: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
3060: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
3070: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
3080: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
3090: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
30a0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
30b0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30c0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
30d0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
30e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
30f0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
3100: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
3110: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
3120: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
3130: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3140: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3150: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3160: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3170: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3180: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3190: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
31a0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
31b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
31c0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
31d0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
31e0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3200: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3210: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3220: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3230: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3240: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3250: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3260: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3270: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3280: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3290: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
32a0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
32b0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
32c0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
32d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
32e0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
32f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3300: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3310: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3320: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3330: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3340: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3350: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3360: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3370: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3380: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3390: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
33a0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
33b0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
33c0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
33d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33e0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
33f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3400: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3410: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3430: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3440: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3450: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3460: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3470: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3480: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3490: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
34a0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
34b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
34c0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
34d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
34e0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
34f0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3500: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3510: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3520: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3530: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3540: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3550: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3570: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3580: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3590: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
35a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
35b0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
35c0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
35d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
35e0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
35f0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
3600: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3610: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3620: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3630: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3640: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3650: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3660: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3670: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3680: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3690: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
36a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
36b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
36c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
36d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
36e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
36f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
3700: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3710: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3720: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3730: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3740: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3750: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3760: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3770: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3780: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3790: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
37a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
37b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
37c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
37d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
37e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
37f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3800: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3810: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3820: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3830: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3840: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3850: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3870: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3880: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3890: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
38a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
38b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
38e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
38f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3910: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3920: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3930: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3940: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3950: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3960: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3970: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3980: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3990: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
39a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
39b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
39c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
39d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
39e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
39f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3a00: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3a10: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3a20: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3a30: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3a40: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3a50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3a60: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3a70: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3a80: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3a90: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3aa0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3ab0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3ad0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3ae0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3af0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3b00: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3b20: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3b30: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3b40: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3b50: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3b60: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3b70: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3bb0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3bc0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3bd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3be0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3bf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3c00: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3c10: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3c20: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3c30: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3c40: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3c60: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3c70: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3c80: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3c90: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3ca0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3cb0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3cc0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3cd0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ce0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3cf0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3d00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3d10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3d20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3d30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3d40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3d50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3d60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3d70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3d80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3d90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3da0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3db0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3dc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3dd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3de0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3df0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3e00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3e10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3e20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3e30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3e40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3e50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3e60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3e70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3e80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3e90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ea0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3eb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3ec0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ed0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ee0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3f00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3f10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3f20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3f30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3f40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3f50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3f60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3f70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3f80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3f90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3fa0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3fb0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3fc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3fe0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3ff0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
4000: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
4010: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4020: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
4040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
4050: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
4060: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
4070: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
4080: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
4090: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
40a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
40b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
40c0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
40d0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
40e0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
40f0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
4100: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
4110: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
4120: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
4130: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4140: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4150: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4160: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4170: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4180: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4190: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
41a0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
41b0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
41c0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
41d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
41e0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
41f0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4200: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4210: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4220: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4230: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4250: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4260: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4270: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4290: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
42a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
42b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
42c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
42d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
42e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
42f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4300: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4310: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4320: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4330: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4340: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4350: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4360: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4370: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4380: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4390: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
43a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
43b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
43e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
43f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4400: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4420: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4430: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4440: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4450: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4460: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4470: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4480: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
44b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
44c0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
44d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
44e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44f0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4500: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4510: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4520: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4530: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4540: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4550: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4560: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4570: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4580: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4590: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
45a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
45b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
45c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
45d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
45e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
45f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4600: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4610: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4620: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4630: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4640: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4670: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4680: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4690: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
46a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
46b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
46c0: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
46d0: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
46e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
46f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4700: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4710: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4730: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4740: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4750: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4770: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4780: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4790: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
47a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
47c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
47d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
47e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
47f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4800: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4810: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4820: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4850: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4860: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4880: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4890: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
48a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
48b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
48c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
48d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
48e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
48f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4900: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4920: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4930: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4940: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4970: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4980: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4990: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
49c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
49d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
49e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4a00: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4a10: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4a20: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4a30: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4a50: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4a60: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4a70: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a90: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4aa0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4ab0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4ac0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ad0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4ae0: 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72 6e    16   /* Intern
4af0: 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23  al use only */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4b10: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4b20: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4b30: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b50: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4b60: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4b70: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4b80: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4ba0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4bb0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4bc0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4bf0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4c00: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4c20: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4c30: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4c40: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4c50: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4c70: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4c80: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4c90: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ca0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4cb0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4cc0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4cf0: 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a   /* Not used */.
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4d20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4d30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4d40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4d70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4d80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4d90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4db0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4dc0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4dd0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4de0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4df0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4e00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4e10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4e20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4e30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4e40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4e50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4e60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4e80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4e90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ea0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4eb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ec0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4ed0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4ee0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4ef0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4f10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4f30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4f40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4f50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4f60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4f70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4f80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4f90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4fa0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4fb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4fc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4fd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4fe0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4ff0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
5000: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
5010: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
5020: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
5030: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
5040: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
5050: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
5060: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
5070: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
5080: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
5090: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
50a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
50b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
50c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
50d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
50e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
50f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5100: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5110: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
5120: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
5130: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
5140: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
5150: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
5160: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
5170: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5180: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5190: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
51a0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
51b0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
51c0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
51d0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
51e0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
51f0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5200: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
5220: 52 4f 52 5f 4d 49 53 53 49 4e 47 5f 43 4f 4c 4c  ROR_MISSING_COLL
5230: 53 45 51 20 20 20 28 53 51 4c 49 54 45 5f 45 52  SEQ   (SQLITE_ER
5240: 52 4f 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ROR | (1<<8)).#d
5250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
5260: 4f 52 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  OR_RETRY        
5270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52       (SQLITE_ERR
5280: 4f 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  OR | (2<<8)).#de
5290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
52a0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
52b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
52c0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5360: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
53a0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
53b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53c0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
53e0: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5420: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
5440: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
5460: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
5480: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5490: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
54c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54d0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
54e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5500: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5510: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5520: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5530: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
5540: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5550: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
5560: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5570: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
5580: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5590: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
55a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
55c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55d0: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
55e0: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
55f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5600: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5610: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5620: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5630: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
5640: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5650: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
5660: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5670: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
5680: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5690: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
56a0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
56b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
56c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
56e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5700: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5710: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5720: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5730: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
5740: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5750: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
5760: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5770: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
5780: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5790: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
57a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
57c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57d0: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
57e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5820: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
5830: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
5840: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5850: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
5860: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5870: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
5880: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5890: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
58a0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
58b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
58c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58d0: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
58e0: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
58f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5900: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5910: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
5920: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5930: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
5940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5950: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
5960: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5970: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
5980: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5990: 54 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f 41  TE_IOERR_BEGIN_A
59a0: 54 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c 49  TOMIC      (SQLI
59b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c 3c  TE_IOERR | (29<<
59c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59d0: 54 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f  TE_IOERR_COMMIT_
59e0: 41 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c 49  ATOMIC     (SQLI
59f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c 3c  TE_IOERR | (30<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41 43  TE_IOERR_ROLLBAC
5a20: 4b 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c 49  K_ATOMIC   (SQLI
5a30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c 3c  TE_IOERR | (31<<
5a40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a50: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5a60: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5a70: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5a80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a90: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5aa0: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5ab0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5ae0: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
5af0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5b00: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
5b20: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
5b30: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5b40: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5b60: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5b70: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5b80: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5ba0: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5bb0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5bc0: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5be0: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5c00: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
5c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c20: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
5c30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c40: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<8)).
5c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c60: 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
5c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c80: 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29  EADONLY | (1<<8)
5c90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5ca0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
5cb0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5cc0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5cd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ce0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5cf0: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5d00: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5d10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d20: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5d30: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5d40: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5d50: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5d60: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5d70: 43 41 4e 54 49 4e 49 54 20 20 20 20 20 20 20 28  CANTINIT       (
5d80: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5d90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5da0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5db0: 59 5f 44 49 52 45 43 54 4f 52 59 20 20 20 20 20  Y_DIRECTORY     
5dc0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5dd0: 59 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  Y | (6<<8)).#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
5df0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5e00: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5e10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e30: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5e40: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e50: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5e60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5e80: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5e90: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ea0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5ec0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5ed0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ee0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5f10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f20: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5f30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f40: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5f50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f60: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5f90: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5fa0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5fb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5fd0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5fe0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ff0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
6020: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6030: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
6040: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
6050: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
6060: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
6070: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
6090: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
60a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
60b0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
60c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
60d0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
60e0: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
60f0: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
6100: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6110: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
6120: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
6130: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
6140: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6150: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
6160: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
6170: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
6180: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6190: 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20  TE_AUTH_USER    
61a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
61b0: 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29  TE_AUTH | (1<<8)
61c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
61d0: 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45  _OK_LOAD_PERMANE
61e0: 4e 54 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45  NTLY     (SQLITE
61f0: 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  _OK | (1<<8))../
6200: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6210: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
6220: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
6230: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
6240: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
6250: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
6260: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
6270: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
6280: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
6290: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
62a0: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
62b0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
62c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
62d0: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
62e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
62f0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
6300: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
6310: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6320: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
6340: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
6350: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
6360: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6370: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6380: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
6390: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
63a0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
63b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
63c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
63d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
63e0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
63f0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
6400: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6410: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
6420: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
6430: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
6440: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6450: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
6460: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
6470: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
6480: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6490: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
64b0: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
64c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
64d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
64e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
64f0: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
6500: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
6510: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6520: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6530: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
6540: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
6550: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
6560: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6570: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6580: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6590: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
65a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
65b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
65c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
65d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
65e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
65f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
6600: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
6610: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
6620: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6640: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
6650: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
6660: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6670: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
6680: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6690: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
66a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
66b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
66c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
66d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
66e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
66f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
6700: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
6710: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
6720: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6730: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6740: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
6750: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6760: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6770: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6780: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6790: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
67a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
67b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
67c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
67d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
67e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
67f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
6800: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
6810: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6820: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6830: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
6840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6850: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6860: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6870: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6890: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
68a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
68b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
68c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
68d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
68e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
68f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6900: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
6910: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
6920: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
6930: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
6940: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
6950: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6960: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6970: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6980: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6990: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
69a0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
69b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
69c0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
69d0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
69f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
6a00: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
6a10: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
6a20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
6a40: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
6a50: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6a60: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6a70: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6a80: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6a90: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6aa0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6ab0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6ac0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6ad0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6ae0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6af0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
6b00: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
6b10: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
6b20: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
6b30: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
6b40: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
6b50: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6b60: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6b70: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6b80: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6ba0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6bb0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6bc0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6bd0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6be0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6bf0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
6c00: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
6c10: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6c20: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
6c30: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6c40: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
6c50: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6c60: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6c70: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6c80: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6c90: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6ca0: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6cb0: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6cc0: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6cd0: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6ce0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6cf0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
6d00: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
6d10: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
6d20: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
6d30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6d40: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6d50: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
6d60: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 20  ndicates that a 
6d70: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
6d80: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
6d90: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6da0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6db0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6dc0: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6dd0: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6de0: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6df0: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6e00: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6e10: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6e20: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a  privileges..**.*
6e30: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6e40: 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20  AP_BATCH_ATOMIC 
6e50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6e60: 68 61 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69  hat the underlyi
6e70: 6e 67 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d  ng.** filesystem
6e80: 20 73 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20   supports doing 
6e90: 6d 75 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f  multiple write o
6ea0: 70 65 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63  perations atomic
6eb0: 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a  ally when those.
6ec0: 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  ** write operati
6ed0: 6f 6e 73 20 61 72 65 20 62 72 61 63 6b 65 74 65  ons are brackete
6ee0: 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e  d by [SQLITE_FCN
6ef0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
6f00: 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53  WRITE] and.** [S
6f10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
6f20: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
6f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6f40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6f60: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6f70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f80: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6f90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6fa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6fb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6fd0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6fe0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ff0: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
7000: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
7010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7020: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
7030: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7040: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
7050: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7060: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
7070: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
7080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7090: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
70a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
70b0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
70c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70d0: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
70e0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
70f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7100: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
7110: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7120: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7140: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
7150: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
7160: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7170: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
7180: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
7190: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
71a0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
71b0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
71c0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
71d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
71e0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
71f0: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
7200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7210: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
7220: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7230: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
7240: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
7250: 48 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  H_ATOMIC        
7260: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f     0x00004000../
7270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
7280: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
7290: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
72a0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
72b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
72c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
72d0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
72e0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
72f0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
7300: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
7310: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
7320: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7330: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
7340: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
7350: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
7360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7370: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
7380: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
7390: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
73a0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
73b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
73c0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
73d0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
73e0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
73f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7400: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
7410: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
7420: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
7430: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
7440: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
7450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7460: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
7470: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
7480: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
7490: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
74a0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
74b0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
74c0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
74d0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
74e0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
74f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7500: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7510: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7520: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7530: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7540: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7550: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7560: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7570: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7580: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
7590: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
75a0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
75b0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
75c0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
75d0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
75e0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
75f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7600: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7610: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7620: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7630: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7640: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7650: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7660: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7670: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7680: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7690: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
76a0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
76b0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
76c0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
76d0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
76e0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
76f0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7700: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7710: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7720: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7730: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7740: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7750: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7760: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7770: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7780: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7790: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
77a0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
77b0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
77c0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
77d0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
77e0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
77f0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7800: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7810: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7820: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7830: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7840: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7850: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7860: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7870: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7880: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7890: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
78a0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
78b0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
78c0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
78d0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
78e0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
78f0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7900: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7910: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7940: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7950: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7960: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7970: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7980: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7990: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
79a0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
79b0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
79c0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
79d0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
79e0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
79f0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7a00: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7a10: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7a20: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7a30: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7a40: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7a50: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7a60: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7a70: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7a80: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7a90: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7aa0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7ab0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7ac0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7ad0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7ae0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7af0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7b00: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7b10: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7b20: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7b30: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7b50: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7b60: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7b70: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7b80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7b90: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7ba0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7bb0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7bc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7bd0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7be0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7bf0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7c00: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7c10: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7c20: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7c30: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7c40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7c50: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7c60: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7c70: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7c80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7c90: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7ca0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7cb0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7cc0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7cd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7ce0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7cf0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7d00: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7d10: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7d20: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7d30: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7d40: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7d50: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7d60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7d70: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7d80: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7d90: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7da0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7db0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7dc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7dd0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7de0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7df0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7e00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7e10: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7e20: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7e30: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7e40: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7e50: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7e60: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7e70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7e80: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7e90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7ea0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7eb0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7ec0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7ed0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7ee0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7ef0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7f00: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7f10: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7f20: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7f30: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7f40: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7f50: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7f60: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7f70: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7f80: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7f90: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7fa0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7fb0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7fc0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7fd0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7fe0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7ff0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
8000: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
8010: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
8020: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
8030: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
8040: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
8050: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
8060: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8070: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
8080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
8090: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80b0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
80c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80d0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
80e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
80f0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
8100: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
8110: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
8120: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
8130: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
8140: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
8150: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
8160: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
8170: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
8180: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
8190: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
81a0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
81b0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
81c0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
81d0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
81e0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
81f0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
8200: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
8210: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
8220: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
8230: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
8240: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
8250: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
8260: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
8270: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
8280: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
8290: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
82a0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
82b0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
82c0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
82d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
82e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
82f0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
8300: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
8310: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
8320: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
8330: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
8340: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
8350: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
8360: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
8370: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
8380: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
8390: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
83a0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
83b0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
83c0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
83d0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
83e0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
83f0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
8400: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
8410: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
8420: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
8430: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
8440: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
8450: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
8460: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
8470: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
8480: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
8490: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
84a0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
84b0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
84c0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
84d0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
84e0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
84f0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8500: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8510: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8520: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8530: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8540: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8550: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8560: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8570: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8580: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
8590: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
85a0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
85b0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
85c0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
85d0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
85e0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
85f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8600: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8610: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8630: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8640: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8650: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8660: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8670: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8680: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8690: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
86a0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
86b0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
86c0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
86d0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
86e0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
86f0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8710: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8720: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8730: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8740: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8750: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8780: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8790: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
87a0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
87b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
87c0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
87d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
87e0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
87f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8800: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8810: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8820: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8840: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8850: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8860: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8870: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8880: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8890: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
88a0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
88b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
88c0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
88d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
88e0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
88f0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8900: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8910: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8920: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8940: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69  MMUTABLE].** <li
8950: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8960: 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  BATCH_ATOMIC].**
8970: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
8980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8990: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
89a0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
89b0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
89c0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
89d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
89e0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
89f0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8a00: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8a10: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8a20: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8a30: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8a40: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8a50: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8a60: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
8a70: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
8a80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8a90: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
8aa0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8ab0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8ac0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8ad0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8ae0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8af0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8b00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8b10: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8b20: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8b30: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8b40: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8b50: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8b60: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
8b70: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
8b80: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
8b90: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
8ba0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8bb0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8bc0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8bd0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8be0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8bf0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8c00: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8c10: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8c20: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8c30: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8c40: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8c50: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8c60: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
8c70: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
8c80: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
8c90: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
8ca0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8cb0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8cc0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8cd0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8ce0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8cf0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8d00: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8d10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8d20: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8d30: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8d40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8d50: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8d60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8d70: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8d80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8d90: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
8da0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8db0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8dc0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8dd0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8de0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8df0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8e00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8e10: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8e20: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8e30: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8e40: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8e50: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8e60: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8e70: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8e80: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
8e90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8ea0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8eb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ec0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8ed0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8ee0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ef0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8f00: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8f10: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8f20: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8f30: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8f40: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8f50: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8f60: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8f70: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8f80: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8f90: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8fa0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8fb0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8fc0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8fd0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8fe0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8ff0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
9000: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
9010: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
9020: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
9030: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
9040: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
9050: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
9060: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
9070: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
9080: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9090: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
90a0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90b0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90c0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
90d0: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
90e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
90f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
9100: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
9110: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
9120: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
9130: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
9140: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
9150: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
9160: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9170: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9180: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
9190: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
91a0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
91b0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
91c0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
91d0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
91e0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
91f0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
9200: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
9210: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
9220: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
9230: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
9240: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
9250: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
9260: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9270: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
9280: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9290: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92b0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
92c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
92d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
92e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
92f0: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
9300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
9310: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
9320: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
9330: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
9340: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
9350: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
9360: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
9370: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
9380: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
9390: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
93a0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
93b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
93c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
93d0: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
93e0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
93f0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
9400: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
9410: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
9420: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
9430: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9440: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
9450: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
9460: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
9470: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
9480: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
9490: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
94a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
94b0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
94c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
94d0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
94e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
94f0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
9500: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
9510: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
9520: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
9530: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
9540: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
9550: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
9560: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
9570: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
9580: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
9590: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
95a0: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
95b0: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
95c0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
95d0: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
95e0: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
95f0: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
9600: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9610: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
9620: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
9630: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
9640: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9650: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
9660: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
9670: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
9680: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
9690: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
96a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
96b0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
96c0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
96d0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
96e0: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
96f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9700: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9710: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9720: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9730: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9740: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9750: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9760: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
9770: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
9780: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
9790: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
97a0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
97b0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
97c0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
97d0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
97e0: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
97f0: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9800: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9810: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9820: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9830: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9840: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9850: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9860: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9880: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9890: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
98a0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
98b0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
98c0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
98d0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
98e0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
98f0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9900: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9910: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9920: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9940: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9950: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9960: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9970: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9990: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
99a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
99b0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
99c0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
99d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
99e0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
99f0: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9a00: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9a10: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9a20: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9a30: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9a40: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9a50: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9a60: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
9a70: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
9a80: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
9a90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9aa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9ab0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9ac0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9ad0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9ae0: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9af0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b00: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9b10: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9b20: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9b30: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9b40: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9b50: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9b60: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
9b70: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9b80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9b90: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9ba0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9bb0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9bc0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9bd0: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9be0: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9bf0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9c00: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9c10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9c20: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9c30: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9c40: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9c50: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9c60: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
9c70: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9c80: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9c90: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9ca0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9cb0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9cc0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9cd0: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9ce0: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9cf0: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9d00: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9d10: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9d20: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
9d30: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
9d40: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9d50: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9d60: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
9d70: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9d80: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9d90: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9da0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9db0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9dc0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9dd0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9de0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9df0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9e00: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9e10: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9e20: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9e30: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9e40: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9e50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9e60: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9e70: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9e80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9e90: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9ea0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9eb0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9ec0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9ed0: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9ee0: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9ef0: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9f00: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9f10: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9f20: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9f30: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9f40: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9f50: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9f60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9f70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9f80: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9f90: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9fb0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9fc0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9fd0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9fe0: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9ff0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
a000: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
a010: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
a020: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
a030: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
a040: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
a050: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a060: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a070: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
a080: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
a090: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
a0a0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
a0b0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
a0c0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
a0d0: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
a0e0: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
a0f0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
a100: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
a110: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
a120: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
a130: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
a140: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
a150: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
a160: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
a170: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
a180: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
a190: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
a1a0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
a1b0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
a1c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
a1d0: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
a1e0: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
a1f0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
a200: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
a210: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
a220: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
a230: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
a240: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
a250: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
a260: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
a270: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
a280: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
a290: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
a2a0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
a2b0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
a2c0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
a2d0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
a2e0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
a2f0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
a300: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
a310: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
a320: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
a330: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
a340: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a350: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
a360: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
a370: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
a380: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
a390: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
a3a0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
a3b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
a3c0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
a3d0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
a3e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
a3f0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
a400: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
a410: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
a420: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
a430: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
a440: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
a450: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
a460: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
a470: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
a480: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a490: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
a4a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a4b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a4c0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
a4d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a4e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a4f0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
a500: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
a510: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
a520: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
a530: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
a540: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
a550: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
a560: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
a570: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
a580: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
a590: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
a5a0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
a5b0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
a5c0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
a5d0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
a5e0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
a5f0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
a600: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
a610: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
a620: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
a630: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
a640: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
a650: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
a660: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
a670: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
a680: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
a690: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
a6a0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
a6b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
a6c0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
a6d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a6e0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
a6f0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
a700: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
a710: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
a720: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a730: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a740: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a750: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a760: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a770: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a780: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a790: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a7a0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
a7b0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
a7c0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
a7d0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
a7e0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
a7f0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
a800: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
a810: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
a820: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
a830: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a840: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a850: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a860: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a870: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a880: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a890: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
a8a0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
a8b0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
a8c0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
a8d0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
a8e0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
a8f0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
a900: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
a910: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
a920: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a930: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
a940: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
a950: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
a960: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
a970: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a980: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a990: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a9a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a9b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a9c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a9d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a9e0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
a9f0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
aa00: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
aa10: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
aa20: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
aa30: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
aa40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
aa50: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
aa60: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
aa70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
aa80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aa90: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
aaa0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
aab0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
aac0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
aad0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
aae0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
aaf0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
ab00: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
ab10: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
ab20: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
ab30: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
ab40: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
ab50: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
ab60: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
ab70: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
ab80: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
ab90: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
aba0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
abb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
abc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
abd0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
abe0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
abf0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
ac00: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ac10: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
ac20: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
ac30: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
ac40: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
ac50: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
ac60: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
ac70: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
ac80: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
ac90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
aca0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
acb0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
acc0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
acd0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
ace0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
acf0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
ad00: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
ad10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ad20: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
ad30: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
ad40: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
ad50: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
ad60: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
ad70: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
ad80: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
ad90: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
ada0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
adb0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
adc0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
add0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
ade0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
adf0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
ae00: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
ae10: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
ae20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
ae30: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
ae40: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
ae50: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
ae60: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
ae70: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
ae80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ae90: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
aea0: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TER]].** ^The [S
aeb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aec0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
aed0: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20  finds a pointer 
aee0: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
aef0: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72  .** [VFSes] curr
af00: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e  ently in use.  ^
af10: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20  (The argument X 
af20: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  in.** sqlite3_fi
af30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51  le_control(db,SQ
af40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
af50: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62  OINTER,X) must b
af60: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73  e.** of type "[s
af70: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e  qlite3_vfs] **".
af80: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77    This opcodes w
af90: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f  ill set *X.** to
afa0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
afb0: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e  e top-level VFS.
afc0: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72  )^.** ^When ther
afd0: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56  e are multiple V
afe0: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20  FS shims in the 
aff0: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f  stack, this opco
b000: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20  de finds the.** 
b010: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20  upper-most shim 
b020: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
b030: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
b040: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
b050: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
b060: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
b070: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
b080: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
b090: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
b0a0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
b0b0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
b0c0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
b0d0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
b0e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
b0f0: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
b100: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
b110: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
b120: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
b130: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b140: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b150: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
b160: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
b170: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
b180: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
b190: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
b1a0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
b1b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
b1c0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
b1d0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
b1e0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
b1f0: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
b200: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
b210: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
b220: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
b230: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
b240: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b250: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
b260: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
b270: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
b280: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
b290: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
b2a0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
b2b0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b2c0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
b2d0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
b2e0: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
b2f0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
b300: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
b310: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
b320: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
b330: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
b340: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
b350: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b360: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b370: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
b380: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b390: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
b3a0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
b3b0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
b3c0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
b3d0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b3e0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b3f0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b400: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
b410: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
b420: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
b430: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
b440: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
b450: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
b460: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
b470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b480: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
b490: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
b4a0: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
b4b0: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
b4c0: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
b4d0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
b4e0: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
b4f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b500: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b510: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
b520: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
b530: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
b540: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
b550: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
b560: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
b570: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
b580: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
b590: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
b5a0: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
b5b0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
b5c0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
b5d0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
b5e0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
b5f0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b600: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
b610: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
b620: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
b630: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
b640: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
b650: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
b660: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
b670: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
b680: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b6a0: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
b6b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
b6c0: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
b6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
b6e0: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
b6f0: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
b700: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
b710: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
b720: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
b730: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
b740: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
b750: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
b760: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
b770: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
b780: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
b790: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
b7a0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
b7b0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
b7c0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
b7d0: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
b7e0: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
b7f0: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
b800: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
b810: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
b820: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
b830: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
b840: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
b850: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
b860: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
b870: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
b880: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
b890: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
b8a0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
b8b0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
b8c0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
b8d0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
b8e0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
b8f0: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
b900: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
b910: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
b920: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
b930: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
b940: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b960: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
b970: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
b980: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
b990: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b9a0: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
b9b0: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
b9c0: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
b9d0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
b9e0: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
b9f0: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
ba00: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
ba10: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
ba20: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
ba30: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
ba40: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
ba50: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
ba60: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
ba70: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
ba80: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
ba90: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
baa0: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
bab0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
bac0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
bad0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
bae0: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
baf0: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
bb00: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
bb10: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
bb20: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
bb30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bb40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
bb50: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
bb60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
bb70: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
bb80: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
bb90: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
bba0: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
bbb0: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
bbc0: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
bbd0: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
bbe0: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
bbf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
bc00: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
bc10: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
bc20: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
bc30: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
bc40: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bc50: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
bc60: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
bc70: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
bc80: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
bc90: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
bca0: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
bcb0: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
bcc0: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
bcd0: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
bce0: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
bcf0: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
bd00: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
bd10: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
bd20: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
bd30: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
bd40: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
bd50: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
bd60: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
bd70: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
bd80: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
bd90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bda0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
bdb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bdc0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
bdd0: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
bde0: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
bdf0: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
be00: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
be10: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
be20: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
be30: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
be40: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
be50: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
be60: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
be70: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
be80: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
be90: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
bea0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
beb0: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
bec0: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
bed0: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
bee0: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
bef0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
bf00: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
bf10: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
bf20: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
bf30: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
bf40: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
bf50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
bf60: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
bf70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bf80: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
bf90: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bfa0: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bfb0: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
bfc0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
bfd0: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
bfe0: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
bff0: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
c000: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
c010: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
c020: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
c030: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
c040: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
c050: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
c060: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c080: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _GET_HANDLE]].**
c090: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c0a0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
c0b0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  DLE] opcode can 
c0c0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
c0d0: 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  n the.** underly
c0e0: 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20  ing native file 
c0f0: 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65  handle associate
c100: 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61  d with a file ha
c110: 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65  ndle.  This file
c120: 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  .** control inte
c130: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
c140: 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72  ent as a pointer
c150: 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c   to a native fil
c160: 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20  e handle and.** 
c170: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
c180: 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65  ting value there
c190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c1b0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
c1c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c1d0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c1e0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
c1f0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
c200: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
c210: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
c220: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c230: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
c240: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
c250: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
c260: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
c270: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
c280: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
c290: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c2a0: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
c2b0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
c2c0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
c2d0: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
c2e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c300: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
c310: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c320: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
c330: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
c340: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
c350: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
c360: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
c370: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
c380: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
c390: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
c3a0: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
c3b0: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
c3c0: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
c3d0: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
c3e0: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
c3f0: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
c400: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
c410: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
c420: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
c430: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
c440: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
c450: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
c460: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c470: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c480: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c490: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20  E_FCNTL_ZIPVFS] 
c4a0: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
c4b0: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20  ented by zipvfs 
c4c0: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a  only. All other.
c4d0: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  ** VFS should re
c4e0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c4f0: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70  OUND for this op
c500: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  code..**.** <li>
c510: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  [[SQLITE_FCNTL_R
c520: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  BU]].** The [SQL
c530: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f  ITE_FCNTL_RBU] o
c540: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c550: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63  nted by the spec
c560: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a  ial VFS used by.
c570: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e  ** the RBU exten
c580: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  sion only.  All 
c590: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64  other VFS should
c5a0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c5b0: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74  OTFOUND for.** t
c5c0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a  his opcode.  .**
c5d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c5e0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c5f0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49  MIC_WRITE]].** I
c600: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
c610: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c620: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72  _WRITE] opcode r
c630: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
c640: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69  , then.** the fi
c650: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73  le descriptor is
c660: 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63   placed in "batc
c670: 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77  h write mode", w
c680: 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c  hich.** means al
c690: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
c6a0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69  te operations wi
c6b0: 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61  ll be deferred a
c6c0: 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69  nd done.** atomi
c6d0: 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78  cally at the nex
c6e0: 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  t [SQLITE_FCNTL_
c6f0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c700: 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a  ITE].  Systems.*
c710: 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75  * that do not su
c720: 70 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d  pport batch atom
c730: 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72  ic writes will r
c740: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c750: 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f  FOUND..** ^Follo
c760: 77 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75  wing a successfu
c770: 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  l SQLITE_FCNTL_B
c780: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c790: 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a  E and prior to.*
c7a0: 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53  * the closing [S
c7b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c7c0: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c7d0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   or.** [SQLITE_F
c7e0: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
c7f0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c  OMIC_WRITE], SQL
c800: 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a  ite will make.**
c810: 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63   no VFS interfac
c820: 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73  e calls on the s
c830: 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  ame [sqlite3_fil
c840: 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  e] file descript
c850: 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72  or.** except for
c860: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57   calls to the xW
c870: 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20  rite method and 
c880: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c890: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20   method.** with 
c8a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
c8b0: 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  ZE_HINT]..**.** 
c8c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c8d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
c8e0: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20  _WRITE]].** The 
c8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c900: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c910: 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  E] opcode causes
c920: 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70   all write.** op
c930: 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74  erations since t
c940: 68 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63  he previous succ
c950: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a  essful call to .
c960: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
c970: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c980: 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f  ITE] to be perfo
c990: 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e  rmed atomically.
c9a0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
c9b0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
c9c0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64  QLITE_OK] if and
c9d0: 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69   only if the wri
c9e0: 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20  tes were.** all 
c9f0: 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73  performed succes
ca00: 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20  sfully and have 
ca10: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74  been committed t
ca20: 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f  o persistent sto
ca30: 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64  rage..** ^Regard
ca40: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
ca50: 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63  or not it is suc
ca60: 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69  cessful, this fi
ca70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
ca80: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
ca90: 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62  criptor out of b
caa0: 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20  atch write mode 
cab0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
cac0: 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20  equent.** write 
cad0: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69  operations are i
cae0: 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e  ndependent..** ^
caf0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
cb00: 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f  r invoke SQLITE_
cb10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
cb20: 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75  MIC_WRITE withou
cb30: 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63  t.** a prior suc
cb40: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
cb50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
cb60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cb70: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
cb80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cb90: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
cba0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
cbb0: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cbc0: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  K_ATOMIC_WRITE] 
cbd0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
cbe0: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
cbf0: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
cc00: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
cc10: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
cc20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
cc30: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cc40: 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62  ] to be rolled b
cc50: 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69  ack..** ^This fi
cc60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
cc70: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
cc80: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
cc90: 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20  h write mode.** 
cca0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
ccb0: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
ccc0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
ccd0: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
cce0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
ccf0: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
cd00: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cd10: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
cd20: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
cd30: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
cd40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cd50: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cd60: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  ..** </ul>.*/.#d
cd70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cd80: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
cd90: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
cda0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cdb0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
cdc0: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
cdd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cde0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
cdf0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
ce00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ce10: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
ce20: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
ce30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
ce40: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
ce50: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
ce60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
ce70: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
ce80: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
ce90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
cea0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
ceb0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
cec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
ced0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
cee0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
cef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
cf00: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
cf10: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
cf20: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
cf30: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
cf40: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
cf50: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
cf60: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cf70: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
cf80: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
cf90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cfa0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cfb0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
cfc0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
cfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cfe0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
cff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
d000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d010: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
d020: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
d030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d040: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
d050: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
d060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d070: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
d080: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
d090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0a0: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
d0b0: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
d0c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d0d0: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
d0e0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
d0f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d100: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
d110: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
d120: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d130: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
d140: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
d150: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
d160: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
d170: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
d180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
d190: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
d1a0: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
d1b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
d1c0: 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  FS              
d1d0: 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51     25.#define SQ
d1e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20  LITE_FCNTL_RBU  
d1f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d200: 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    26.#define SQL
d210: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
d220: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
d230: 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   27.#define SQLI
d240: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
d250: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
d260: 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  28.#define SQLIT
d270: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
d280: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
d290: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
d2a0: 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20  _FCNTL_PDB      
d2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30                30
d2c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d2d0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
d2e0: 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a  IC_WRITE     31.
d2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d300: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
d310: 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23  IC_WRITE    32.#
d320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d330: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
d340: 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 0a 2f  MIC_WRITE  33../
d350: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
d360: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
d370: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
d380: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
d390: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
d3a0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
d3b0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
d3c0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
d3d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
d3e0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
d3f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
d400: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
d410: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
d420: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
d430: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d440: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
d450: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
d460: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
d470: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
d480: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
d490: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
d4a0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
d4b0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
d4c0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
d4d0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
d4e0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
d4f0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
d500: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
d510: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
d520: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
d530: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
d540: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
d550: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
d560: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
d570: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
d580: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
d590: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
d5a0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
d5b0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
d5c0: 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45  3REF: Loadable E
d5d0: 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a  xtension Thunk.*
d5e0: 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
d5f0: 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c  o the opaque sql
d600: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
d610: 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70  s structure is p
d620: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
d630: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
d640: 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20  to entry points 
d650: 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74  of [loadable ext
d660: 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a  ensions].  This.
d670: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ** structure mus
d680: 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69  t be typedefed i
d690: 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20  n order to work 
d6a0: 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20  around compiler 
d6b0: 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73  warnings.** on s
d6c0: 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  ome platforms..*
d6d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
d6e0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d6f0: 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70  tines sqlite3_ap
d700: 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a  i_routines;../*.
d710: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
d720: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
d730: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
d740: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
d750: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
d760: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
d770: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
d780: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
d790: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
d7a0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
d7b0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
d7c0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
d7d0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
d7e0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
d7f0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
d800: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
d810: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
d820: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
d830: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
d840: 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65 72 66  * The VFS interf
d850: 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73  ace is sometimes
d860: 20 65 78 74 65 6e 64 65 64 20 62 79 20 61 64 64   extended by add
d870: 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20  ing new methods 
d880: 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e  onto.** the end.
d890: 20 20 45 61 63 68 20 74 69 6d 65 20 73 75 63 68    Each time such
d8a0: 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63   an extension oc
d8b0: 63 75 72 73 2c 20 74 68 65 20 69 56 65 72 73 69  curs, the iVersi
d8c0: 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69  on field.** is i
d8d0: 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65  ncremented.  The
d8e0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
d8f0: 73 74 61 72 74 65 64 20 6f 75 74 20 61 73 20 31  started out as 1
d900: 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76   in.** SQLite [v
d910: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e  ersion 3.5.0] on
d920: 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c   [dateof:3.5.0],
d930: 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20   then increased 
d940: 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c  to 2.** with SQL
d950: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37  ite [version 3.7
d960: 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .0] on [dateof:3
d970: 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20  .7.0], and then 
d980: 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20  increased.** to 
d990: 33 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  3 with SQLite [v
d9a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e  ersion 3.7.6] on
d9b0: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e   [dateof:3.7.6].
d9c0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
d9d0: 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70  lds.** may be ap
d9e0: 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71  pended to the sq
d9f0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
da00: 20 61 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f   and the iVersio
da10: 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69  n value.** may i
da20: 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e  ncrease again in
da30: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
da40: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e   of SQLite..** N
da50: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
da60: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
da70: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
da80: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
da90: 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72  he transition fr
daa0: 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65  om.** SQLite [ve
dab0: 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20  rsion 3.5.9] to 
dac0: 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20  [version 3.6.0] 
dad0: 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30  on [dateof:3.6.0
dae0: 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65  ].** and yet the
daf0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
db00: 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64  was not modified
db10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
db20: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
db30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
db40: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
db50: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
db60: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
db70: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
db80: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
db90: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
dba0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
dbb0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
dbc0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
dbd0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
dbe0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
dbf0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
dc00: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
dc10: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
dc20: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
dc30: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
dc40: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
dc50: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
dc60: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
dc70: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
dc80: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
dc90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
dca0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
dcb0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
dcc0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
dcd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
dce0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
dcf0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
dd00: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
dd10: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
dd20: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
dd30: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
dd40: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
dd50: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
dd60: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
dd70: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
dd80: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
dd90: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
dda0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
ddb0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
ddc0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
ddd0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
dde0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
ddf0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
de00: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
de10: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
de20: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
de30: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
de40: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
de50: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
de60: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
de70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
de80: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
de90: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
dea0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
deb0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
dec0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
ded0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
dee0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
def0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
df00: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
df10: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
df20: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
df30: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
df40: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
df50: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
df60: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
df70: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
df80: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
df90: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
dfa0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
dfb0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
dfc0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
dfd0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
dfe0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
dff0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
e000: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
e010: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
e020: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
e030: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
e040: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
e050: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
e060: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
e070: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
e080: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
e090: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
e0a0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
e0b0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
e0c0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
e0d0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
e0e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
e0f0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
e100: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
e110: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
e120: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
e130: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
e140: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
e150: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
e160: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
e170: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
e180: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
e190: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
e1a0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
e1b0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
e1c0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
e1d0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
e1e0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
e1f0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
e200: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
e210: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
e220: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
e230: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
e240: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
e250: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
e260: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
e270: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
e280: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
e290: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
e2a0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
e2b0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
e2c0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
e2d0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
e2e0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
e2f0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
e300: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
e310: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e320: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
e330: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
e340: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
e350: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
e360: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
e370: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
e380: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
e390: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
e3a0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
e3b0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
e3c0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
e3d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
e3e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
e3f0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
e400: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
e410: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
e420: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
e430: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e440: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
e450: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e460: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
e470: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e480: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
e490: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e4a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
e4b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e4c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
e4d0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
e4e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e4f0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
e500: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e510: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
e520: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e530: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
e540: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
e550: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
e560: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
e570: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
e580: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
e590: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
e5a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
e5b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
e5c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
e5d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
e5e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
e5f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
e600: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
e610: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
e620: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
e630: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
e640: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
e650: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
e660: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
e670: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
e680: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
e690: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
e6a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
e6b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e6c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
e6d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
e6e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
e6f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
e700: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
e710: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
e720: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
e730: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
e740: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
e750: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
e760: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
e770: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
e780: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
e790: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
e7a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
e7b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
e7c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e7d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
e7e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e7f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
e800: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
e810: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
e820: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
e830: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
e840: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
e850: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
e860: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
e870: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e880: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
e890: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
e8a0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
e8b0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
e8c0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
e8d0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
e8e0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
e8f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
e900: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
e910: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
e920: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
e930: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
e940: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
e950: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
e960: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
e970: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
e980: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
e990: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
e9a0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
e9b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
e9c0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
e9d0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
e9e0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
e9f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
ea00: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
ea10: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
ea20: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
ea30: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
ea40: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
ea50: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
ea60: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
ea70: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
ea80: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
ea90: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
eaa0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
eab0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
eac0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
ead0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
eae0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
eaf0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
eb00: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
eb10: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
eb20: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
eb30: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
eb40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
eb50: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
eb60: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
eb70: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
eb80: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
eb90: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
eba0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
ebb0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
ebc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
ebd0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
ebe0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
ebf0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
ec00: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
ec10: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ec20: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
ec30: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
ec40: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
ec50: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
ec60: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
ec90: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
eca0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
ecb0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
ecc0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
ecd0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
ece0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
ecf0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
ed00: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
ed10: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
ed20: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ed30: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ed40: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ed50: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ed60: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
ed70: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
ed80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ed90: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
eda0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
edb0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
edc0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
edd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ede0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
edf0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
ee00: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
ee10: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
ee20: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
ee30: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
ee40: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
ee50: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
ee60: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
ee70: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
ee80: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
ee90: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
eea0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
eeb0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
eec0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
eed0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
eee0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
eef0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
ef00: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
ef10: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
ef20: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
ef30: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
ef40: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
ef50: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
ef60: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
ef70: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
ef80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
ef90: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
efa0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
efb0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
efc0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
efd0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
efe0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
eff0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
f000: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
f010: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
f020: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f030: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
f040: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
f050: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
f060: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
f070: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
f080: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
f090: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
f0a0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
f0b0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
f0c0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
f0d0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
f0e0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
f0f0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
f100: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
f110: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
f120: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
f130: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
f140: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
f150: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
f160: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
f170: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
f180: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
f190: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
f1a0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
f1b0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
f1c0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
f1d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
f1e0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
f1f0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
f200: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
f210: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
f220: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
f230: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
f240: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
f250: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
f260: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
f270: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
f280: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
f290: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
f2a0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
f2b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
f2c0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
f2d0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
f2e0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
f2f0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
f300: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
f310: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
f320: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
f330: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
f340: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
f350: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
f360: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
f370: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
f380: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
f390: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
f3a0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
f3b0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
f3c0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
f3d0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
f3e0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
f3f0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
f400: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
f410: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
f420: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
f430: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
f440: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
f450: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
f460: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
f470: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
f480: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
f490: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
f4a0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
f4b0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
f4c0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
f4d0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
f4e0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
f4f0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
f500: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
f510: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
f520: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
f530: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
f540: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
f550: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
f560: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
f570: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
f580: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
f590: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
f5a0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
f5b0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
f5c0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
f5d0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
f5e0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
f5f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
f600: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
f610: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
f620: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
f630: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
f640: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
f650: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
f660: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
f670: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
f680: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
f690: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
f6a0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
f6b0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
f6c0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
f6d0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
f6e0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
f6f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
f700: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
f710: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
f720: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
f730: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
f740: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
f750: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
f760: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
f770: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f780: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
f790: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
f7a0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
f7b0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
f7c0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
f7d0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
f7e0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
f7f0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
f800: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
f810: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
f820: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
f830: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
f840: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
f850: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
f860: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
f870: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
f880: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f890: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
f8a0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
f8b0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
f8c0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
f8d0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
f8e0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
f8f0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
f900: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
f910: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
f920: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f930: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
f940: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
f950: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
f960: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
f970: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
f980: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f990: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f9a0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
f9b0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
f9c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f9d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f9e0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
f9f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
fa00: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
fa10: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
fa20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
fa30: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
fa40: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
fa50: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
fa60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fa70: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
fa80: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
fa90: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
faa0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
fab0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
fac0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
fad0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
fae0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
faf0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
fb00: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
fb10: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
fb20: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
fb30: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
fb40: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
fb50: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
fb60: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
fb70: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
fb80: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
fb90: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
fba0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
fbb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
fbc0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
fbd0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
fbe0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
fbf0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
fc00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
fc10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
fc20: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
fc30: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
fc40: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
fc50: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
fc60: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
fc70: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
fc80: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
fc90: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
fca0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
fcb0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
fcc0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
fcd0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
fce0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
fcf0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
fd00: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
fd10: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
fd20: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
fd30: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
fd40: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
fd50: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
fd60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fd70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fd80: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
fd90: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
fda0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
fdb0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
fdc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fdd0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
fde0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
fdf0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
fe00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fe10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fe20: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
fe30: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
fe40: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
fe50: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
fe60: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
fe70: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
fe80: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
fe90: 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  nded in future v
fea0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
feb0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
fec0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
fed0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
fee0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
fef0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ff00: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
ff10: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
ff20: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ff30: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
ff40: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
ff50: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
ff60: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
ff70: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
ff80: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
ff90: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
ffa0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
ffb0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
ffc0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
ffd0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
ffe0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
fff0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
10000 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
10010 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
10020 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
10030 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
10040 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
10050 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10060 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
10070 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
10080 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
10090 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
100a0 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
100b0 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
100c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
100d0 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
100e0 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
100f0 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
10100 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
10110 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
10120 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10130 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
10140 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
10150 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
10160 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
10170 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
10180 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
10190 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
101a0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
101b0 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
101c0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
101d0 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
101e0 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
101f0 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
10200 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
10210 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
10220 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
10230 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
10240 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
10250 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
10260 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
10270 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
10280 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10290 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
102a0 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
102c0 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
102d0 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
102e0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
102f0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
10300 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
10310 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
10320 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
10330 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
10340 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
10350 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
10360 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
10370 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
10380 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
10390 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
103a0 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
103b0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
103c0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
103d0 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
103e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
103f0 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
10400 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
10410 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
10420 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
10430 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
10440 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
10450 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10460 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
10470 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10480 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
10490 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
104a0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
104b0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
104c0 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
104d0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
104e0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
104f0 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
10500 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
10510 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
10520 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
10530 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
10540 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
10550 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
10560 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
10570 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
10580 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10590 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
105a0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
105b0 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
105c0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
105d0 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
105e0 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
105f0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
10600 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
10610 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
10620 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
10630 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
10640 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10650 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
10660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10670 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
10680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10690 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
106a0 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
106b0 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
106c0 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
106d0 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
106e0 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
106f0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
10700 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
10710 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
10720 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
10730 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
10740 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
10750 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
10760 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
10770 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
10780 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
10790 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
107a0 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
107b0 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
107c0 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
107d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
107e0 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
107f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
10800 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10810 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10820 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
10830 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
10840 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
10850 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
10860 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
10870 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
10880 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
10890 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
108a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
108b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
108c0 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
108d0 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
108e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
108f0 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
10900 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
10910 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
10920 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
10930 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
10940 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
10950 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
10960 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
10970 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
10980 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
10990 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
109a0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
109b0 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
109c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
109d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
109e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
109f0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
10a00 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
10a10 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
10a20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
10a30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10a40 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
10a50 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
10a60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10a70 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
10a80 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
10a90 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
10aa0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ab0 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
10ac0 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
10ad0 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
10ae0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
10af0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
10b00 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10b10 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
10b20 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10b30 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10b40 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
10b50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
10b60 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
10b70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10b80 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
10b90 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
10ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10bb0 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
10bc0 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
10bd0 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
10be0 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
10bf0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10c00 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
10c10 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
10c20 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10c30 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
10c40 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
10c50 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
10c60 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
10c70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
10c80 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
10c90 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
10ca0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
10cb0 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
10cc0 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
10cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10ce0 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
10cf0 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
10d00 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
10d10 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
10d20 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
10d30 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
10d40 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
10d50 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
10d60 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
10d70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10d80 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
10d90 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10da0 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
10db0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10dc0 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
10dd0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10de0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
10df0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10e00 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
10e10 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
10e20 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
10e30 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
10e40 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
10e50 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
10e60 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
10e70 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
10e80 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
10e90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
10ea0 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
10eb0 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
10ec0 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
10ed0 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
10ee0 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
10ef0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
10f00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
10f10 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
10f20 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
10f30 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
10f40 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
10f50 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
10f60 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
10f70 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
10f80 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
10f90 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10fa0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
10fb0 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
10fc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10fd0 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
10fe0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ff0 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
11000 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
11010 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
11020 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
11030 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
11040 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
11050 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
11060 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
11070 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
11080 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11090 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
110a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
110b0 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
110c0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
110d0 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
110e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
110f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
11100 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
11110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11120 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
11130 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11140 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
11150 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
11160 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
11170 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
11180 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
11190 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
111a0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
111b0 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
111c0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
111e0 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11210 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
11220 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
11230 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
11240 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11250 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
11260 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
11270 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
11280 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
11290 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
112a0 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
112b0 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
112c0 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
112d0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
112e0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
112f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11300 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
11310 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
11320 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
11330 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
11340 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11350 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
11360 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
11370 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
11380 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
11390 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
113a0 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
113b0 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
113c0 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
113d0 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
113e0 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
113f0 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
11400 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
11410 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
11420 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
11430 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
11440 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
11450 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
11460 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
11470 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
11480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
11490 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
114a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
114b0 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
114c0 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
114d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
114e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
114f0 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
11500 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
11510 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
11520 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
11530 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
11540 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11550 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
11560 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
11570 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
11580 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
11590 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
115a0 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
115b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
115c0 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
115d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
115e0 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
115f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
11600 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
11610 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
11620 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
11630 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
11640 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
11650 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
11660 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
11670 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
11680 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
11690 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
116a0 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
116b0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
116c0 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
116d0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
116e0 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
116f0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
11700 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
11710 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
11720 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11730 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
11740 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
11750 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
11760 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
11770 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
11780 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
11790 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
117a0 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
117b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
117c0 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
117d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
117e0 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
117f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11800 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11810 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
11820 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
11830 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
11840 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11850 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11860 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
11870 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
11880 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
11890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
118a0 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
118b0 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
118c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
118d0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
118e0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
118f0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
11900 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
11910 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
11920 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
11930 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
11940 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
11950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
11960 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
11970 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
11980 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
11990 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
119a0 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
119b0 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
119c0 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
119d0 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
119e0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
119f0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
11a00 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
11a10 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
11a20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11a40 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
11a50 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
11a60 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
11a70 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
11a80 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
11a90 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
11aa0 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
11ab0 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
11ac0 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
11ad0 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
11ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11af0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
11b00 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
11b10 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
11b20 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
11b30 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
11b40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11b50 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
11b60 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
11b70 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
11b80 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
11b90 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
11ba0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
11bb0 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
11bc0 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
11bd0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
11be0 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
11bf0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
11c00 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
11c10 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
11c20 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
11c30 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
11c40 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
11c50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
11c60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11c70 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
11c80 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
11c90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11ca0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
11cb0 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
11cc0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
11cd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
11ce0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
11cf0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
11d00 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
11d10 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
11d20 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
11d30 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
11d40 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
11d50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11d60 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11d70 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11d80 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
11d90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11da0 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
11db0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
11dc0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
11dd0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
11de0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
11df0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
11e00 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
11e10 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
11e20 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
11e30 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11e40 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
11e50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
11e60 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
11e70 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
11e80 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
11e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ea0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
11eb0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
11ec0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11ed0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11ee0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
11ef0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
11f00 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
11f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11f20 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
11f30 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
11f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f50 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
11f60 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
11f70 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
11f80 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11f90 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
11fa0 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
11fb0 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
11fc0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
11fd0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11fe0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
11ff0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
12000 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
12010 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
12020 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
12030 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
12040 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
12050 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
12060 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
12070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
12080 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
12090 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
120a0 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
120b0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
120c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
120d0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
120e0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
120f0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
12100 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
12110 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
12120 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
12130 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
12140 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
12150 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
12160 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
12170 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
12180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
12190 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
121a0 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
121b0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
121c0 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
121d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
121e0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
121f0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
12200 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12210 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
12220 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
12230 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
12240 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
12250 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
12260 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
12270 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12280 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
12290 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
122a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122b0 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
122c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
122d0 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
122e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
122f0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
12300 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
12310 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
12320 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
12330 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
12340 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
12350 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
12360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12370 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
12380 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
12390 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
123a0 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
123b0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
123c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
123d0 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
123e0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
123f0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
12400 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
12410 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
12420 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
12430 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
12440 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
12450 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
12460 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
12470 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
12480 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
12490 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
124a0 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
124b0 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
124c0 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
124d0 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
124e0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
124f0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
12500 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
12510 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
12520 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
12530 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
12540 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
12550 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
12560 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
12570 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
12580 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12590 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
125a0 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
125b0 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
125c0 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
125d0 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
125e0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
125f0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
12600 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
12610 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
12620 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
12630 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
12640 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
12650 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
12660 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
12670 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
12680 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12690 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
126a0 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
126b0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
126c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
126d0 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
126e0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
126f0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
12700 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
12710 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
12720 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
12730 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
12740 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12750 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
12760 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
12770 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
12780 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
12790 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
127a0 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
127b0 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
127c0 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
127d0 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
127e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
127f0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
12800 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
12810 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
12820 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
12830 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
12840 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
12850 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
12860 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
12870 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12880 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
12890 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
128a0 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
128b0 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
128c0 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
128d0 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
128e0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
128f0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
12900 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
12910 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
12920 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
12930 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
12940 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
12950 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12960 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
12970 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
12980 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
12990 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
129a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
129b0 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
129c0 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
129d0 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
129e0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
129f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12a00 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
12a10 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
12a20 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
12a30 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
12a40 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
12a50 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
12a60 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
12a70 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12a80 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
12a90 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
12aa0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12ab0 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
12ac0 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
12ad0 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
12ae0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
12af0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
12b00 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
12b10 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
12b20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
12b30 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
12b40 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
12b50 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
12b60 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
12b70 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
12b80 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
12b90 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
12ba0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
12bb0 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
12bc0 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
12bd0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12be0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
12bf0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
12c00 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
12c10 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
12c20 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
12c30 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
12c40 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
12c50 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
12c60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
12c70 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
12c80 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
12c90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
12ca0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12cb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12cc0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
12cd0 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
12ce0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
12cf0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
12d00 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
12d10 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
12d20 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
12d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12d40 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
12d50 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
12d60 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
12d70 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
12d80 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
12d90 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
12da0 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
12db0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
12dc0 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
12dd0 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
12de0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
12df0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
12e00 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
12e10 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
12e20 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
12e30 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12e40 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
12e50 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
12e60 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12e70 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
12e80 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
12e90 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
12ea0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12eb0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
12ec0 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
12ed0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
12ee0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
12ef0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
12f00 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
12f10 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
12f20 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
12f30 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
12f40 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
12f50 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
12f60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
12f70 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12f80 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
12f90 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
12fa0 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
12fb0 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
12fc0 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
12fd0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
12fe0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12ff0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
13000 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13010 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
13020 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
13030 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
13040 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13050 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13060 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
13070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
13080 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
13090 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
130a0 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
130b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
130c0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
130d0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
130e0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
130f0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
13100 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
13110 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
13120 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
13130 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
13140 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
13150 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
13160 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
13170 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13180 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
13190 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
131a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
131b0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
131c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
131d0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
131e0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
131f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
13200 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
13210 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
13220 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
13230 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
13240 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
13250 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
13260 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
13270 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
13280 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13290 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
132a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
132b0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
132c0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
132d0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
132e0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
132f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
13300 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
13310 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
13320 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13330 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
13340 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13350 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
13360 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
13370 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
13380 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
13390 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
133a0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
133b0 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
133c0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
133d0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
133e0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
133f0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
13400 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
13410 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
13420 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
13430 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
13440 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
13450 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13460 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13470 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13480 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13490 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
134a0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
134b0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
134c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
134d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
134e0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
134f0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
13500 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
13510 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13520 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13530 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13540 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
13550 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13560 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13570 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13580 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13590 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
135a0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
135b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
135c0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
135d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
135e0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
135f0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
13600 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13610 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13620 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13630 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
13640 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13650 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13660 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
13670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13680 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13690 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
136a0 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
136b0 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
136c0 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
136d0 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
136e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
136f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
13700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13710 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
13720 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
13730 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
13740 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
13750 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
13760 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
13770 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
13780 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
13790 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
137a0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
137b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
137c0 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
137d0 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
137e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
137f0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13800 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13810 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13820 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13830 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13840 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13850 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
13860 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
13870 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13880 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
13890 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
138a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
138b0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
138c0 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
138d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
138e0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
138f0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
13900 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13910 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13920 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13930 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
13940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13950 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13960 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13970 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13980 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13990 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
139a0 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
139b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
139c0 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
139d0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
139e0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
139f0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
13a00 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
13a10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
13a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13a30 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13a40 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
13a50 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
13a60 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
13a70 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13a80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
13a90 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
13aa0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
13ab0 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
13ac0 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
13ad0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13ae0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
13af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
13b00 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
13b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
13b20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
13b30 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
13b40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
13b50 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
13b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13b70 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
13b80 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
13b90 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
13ba0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13bb0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13bc0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13bd0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13be0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13bf0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13c00 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13c10 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
13c20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
13c30 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13c50 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13c60 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13c70 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13c80 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13c90 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
13ca0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13cb0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13cc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13cd0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13cf0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13d00 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13d10 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
13d20 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13d30 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13d40 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
13d50 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13d60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13d70 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13d80 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
13d90 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13da0 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
13db0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
13dc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13dd0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
13de0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
13df0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13e00 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
13e10 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
13e20 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
13e30 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
13e40 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
13e50 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13e60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13e70 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
13e80 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
13e90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13ea0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
13eb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ec0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13ed0 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13ee0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13ef0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
13f00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13f10 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
13f20 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13f30 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13f40 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
13f50 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13f60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13f70 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13f80 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
13f90 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13fa0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13fb0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13fc0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13fd0 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
13fe0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13ff0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14000 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14010 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14020 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
14030 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14040 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14050 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
14060 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
14070 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
14080 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
14090 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
140a0 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
140b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
140c0 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
140d0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
140e0 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
140f0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
14100 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14110 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20  IG_SMALL_MALLOC 
14120 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
14130 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a  gle argument of.
14140 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  ** type int, int
14150 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
14160 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20  olean, which if 
14170 74 72 75 65 20 70 72 6f 76 69 64 65 73 20 61 20  true provides a 
14180 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74  hint to.** SQLit
14190 65 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64  e that it should
141a0 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d   avoid large mem
141b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
141c0 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  if possible..** 
141d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20  SQLite will run 
141e0 66 61 73 74 65 72 20 69 66 20 69 74 20 69 73 20  faster if it is 
141f0 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72  free to make lar
14200 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ge memory alloca
14210 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f  tions,.** but so
14220 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  me application m
14230 69 67 68 74 20 70 72 65 66 65 72 20 74 6f 20 72  ight prefer to r
14240 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63  un slower in exc
14250 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61  hange for.** gua
14260 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65  rantees about me
14270 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69  mory fragmentati
14280 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73 73  on that are poss
14290 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a  ible if large.**
142a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65   allocations are
142b0 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20   avoided.  This 
142c0 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  hint is normally
142d0 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   off..** </dd>.*
142e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
142f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
14300 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14310 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
14320 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
14330 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14340 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
14350 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
14360 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
14370 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
14380 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
14390 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
143a0 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
143b0 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
143c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
143d0 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
143e0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
143f0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14400 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
14410 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
14420 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
14430 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
14440 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
14450 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
14460 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14470 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14480 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
14490 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
144a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
144b0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
144c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
144d0 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
144e0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
144f0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
14500 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14510 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
14520 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
14530 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
14540 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
14550 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
14560 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
14570 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
14580 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14590 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
145a0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
145b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
145d0 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
145e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
145f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
14600 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14610 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73  CRATCH option is
14620 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e   no longer used.
14630 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14640 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14650 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
14660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14670 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
14680 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14690 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
146a0 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  E option specifi
146b0 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c  es a memory pool
146c0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
146d0 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
146e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
146f0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
14700 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
14710 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14720 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
14730 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14740 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20  n is a no-op if 
14750 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
14760 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
14770 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14780 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
14790 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
147a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a  ONFIG_PCACHE2]..
147b0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
147c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
147d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
147e0 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
147f0 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
14800 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
14810 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65  (pMem), the size
14820 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61   of each page ca
14830 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a  che line (sz),.*
14840 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  * and the number
14850 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20   of cache lines 
14860 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
14870 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
14880 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
14890 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
148a0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
148b0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
148c0 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36  en 512 and 65536
148d0 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72  ) plus some extr
148e0 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68  a bytes for each
148f0 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
14900 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66    ^The number of
14910 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65   extra bytes nee
14920 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ded by the page 
14930 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65  header.** can be
14940 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
14950 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  g [SQLITE_CONFIG
14960 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a  _PCACHE_HDRSZ]..
14970 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  ** ^It is harmle
14980 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
14990 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
149a0 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20  ,.** for the sz 
149b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
149c0 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65  larger than nece
149d0 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d  ssary.  The pMem
149e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
149f0 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
14a00 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20  LL pointer or a 
14a10 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
14a20 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
14a30 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
14a40 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
14a50 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73   bytes, otherwis
14a60 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  e.** subsequent 
14a70 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
14a80 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fined..** ^When 
14a90 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  pMem is not NULL
14aa0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74  , SQLite will st
14ab0 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20  rive to use the 
14ac0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a  memory provided.
14ad0 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61  ** to satisfy pa
14ae0 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20  ge cache needs, 
14af0 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20  falling back to 
14b00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14b10 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20  )] if.** a page 
14b20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61  cache line is la
14b30 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74  rger than sz byt
14b40 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20  es or if all of 
14b50 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a  the pMem buffer.
14b60 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ** is exhausted.
14b70 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20  .** ^If pMem is 
14b80 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f  NULL and N is no
14b90 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63  n-zero, then eac
14ba0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14bb0 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e  ction.** does an
14bc0 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c   initial bulk al
14bd0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67  location for pag
14be0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a  e cache memory.*
14bf0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
14c00 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63  malloc()] suffic
14c10 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65  ient for N cache
14c20 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70   lines if N is p
14c30 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66  ositive or.** of
14c40 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69   -1024*N bytes i
14c50 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  f N is negative,
14c60 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61   . ^If additiona
14c70 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
14c80 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
14c90 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
14ca0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
14cb0 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63  initial.** alloc
14cc0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69  ation, then SQLi
14cd0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
14ce0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65  te3_malloc()] se
14cf0 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63  parately for eac
14d00 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  h.** additional 
14d10 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64  cache line. </dd
14d20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14d30 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
14d40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d50 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
14d60 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14d70 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
14d80 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
14d90 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
14da0 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  er .** that SQLi
14db0 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20  te will use for 
14dc0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
14dd0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
14de0 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65  tion needs.** be
14df0 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
14e00 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  ded for by [SQLI
14e10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14e20 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
14e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14e40 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14e50 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
14e60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
14e70 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
14e80 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
14e90 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
14ea0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
14eb0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
14ec0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
14ed0 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
14ee0 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
14ef0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14f00 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14f10 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
14f20 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14f30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
14f40 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
14f50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14f60 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
14f70 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
14f80 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14f90 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
14fa0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14fb0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14fc0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14fd0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14fe0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14ff0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
15000 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
15010 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
15020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
15030 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
15040 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
15050 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
15060 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
15070 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
15080 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15090 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
150a0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
150b0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
150c0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
150d0 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
150e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
150f0 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
15100 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
15110 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
15120 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
15130 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
15140 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
15150 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
15160 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
15170 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
15180 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
15190 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
151a0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
151b0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
151c0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
151d0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
151e0 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
151f0 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
15200 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15210 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
15220 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15230 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
15240 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15250 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
15260 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15270 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15280 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
15290 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
152a0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
152b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
152c0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
152d0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
152e0 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
152f0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
15300 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
15310 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
15320 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
15330 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
15340 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
15350 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
15360 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
15370 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
15380 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15390 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
153a0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
153b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
153c0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
153d0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
153e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
153f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
15400 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
15410 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
15420 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
15430 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
15440 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
15450 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
15460 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
15470 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
15480 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
15490 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
154a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
154b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
154c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
154d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
154e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
154f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15500 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
15510 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15520 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
15530 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15540 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15550 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
15560 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15570 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
15580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15590 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
155a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
155b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
155c0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
155d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
155e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
155f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
15600 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
15610 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
15620 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
15630 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
15640 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
15650 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
15660 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
15670 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
15680 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
15690 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
156a0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
156b0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
156c0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
156d0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
156e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
156f0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15700 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15710 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15720 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15730 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15740 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
15750 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
15760 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
15770 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
15780 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
15790 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
157a0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
157b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
157c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
157d0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
157e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
157f0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15800 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15810 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
15820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15830 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15840 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15850 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15860 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
15870 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
15880 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
15890 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
158a0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
158b0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
158c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
158d0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
158e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
158f0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15900 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15910 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
15920 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
15930 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
15940 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
15950 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
15960 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
15970 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15980 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
15990 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
159a0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
159b0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
159c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
159d0 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
159e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
159f0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
15a00 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
15a10 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
15a20 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
15a30 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
15a40 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15a50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15a60 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
15a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15a80 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
15a90 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15aa0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
15ab0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15ac0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15ad0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
15ae0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
15af0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15b00 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
15b10 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
15b20 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
15b30 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
15b40 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
15b50 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
15b60 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
15b70 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
15b80 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15b90 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
15ba0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15bb0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15bc0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
15bd0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15be0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15bf0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15c00 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
15c10 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15c20 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15c30 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15c40 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
15c50 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15c60 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
15c70 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
15c80 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
15c90 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
15ca0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
15cb0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
15cc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15cd0 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
15ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15cf0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
15d00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15d10 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
15d20 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
15d30 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
15d40 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
15d50 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15d80 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
15d90 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
15da0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
15db0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
15dc0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
15dd0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
15de0 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
15df0 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
15e00 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
15e10 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
15e20 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
15e30 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
15e40 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
15e50 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
15e60 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
15e70 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
15e80 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
15ea0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
15eb0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
15ec0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
15ed0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
15ee0 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
15ef0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
15f00 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
15f10 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
15f20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15f30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15f40 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15f50 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
15f60 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
15f70 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
15f80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15f90 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
15fa0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
15fb0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15fc0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15fd0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15ff0 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
16000 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
16010 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
16020 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
16030 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
16040 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
16050 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
16060 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
16070 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
16080 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
16090 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
160a0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
160b0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
160c0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
160d0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
160e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
160f0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
16100 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
16110 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
16120 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
16130 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
16140 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
16150 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
16160 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16170 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16180 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
16190 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
161a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
161b0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
161c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
161d0 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
161e0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
161f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16200 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
16210 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
16220 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
16230 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16240 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
16250 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16260 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
16270 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
16280 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
16290 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
162a0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
162b0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
162c0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
162d0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
162e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
162f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
16300 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
16310 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
16320 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
16330 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
16340 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
16350 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
16360 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
16370 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
16380 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
16390 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
163a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
163b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
163c0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
163d0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
163e0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
163f0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
16400 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
16410 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
16420 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
16430 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
16440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16450 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
16460 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
16470 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
16480 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
16490 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
164a0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
164b0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
164c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
164d0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
164e0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
164f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16500 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16510 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
16520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16530 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
16540 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16550 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16560 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
16570 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16580 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
16590 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
165a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
165b0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
165c0 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
165d0 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
165e0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
165f0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
16600 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
16610 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
16620 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
16630 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
16640 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
16650 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
16660 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
16670 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
16680 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
16690 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
166a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
166b0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
166c0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
166d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
166e0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
166f0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
16700 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
16710 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
16720 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
16730 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
16740 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
16750 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
16760 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
16770 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
16780 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
16790 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
167a0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
167b0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
167c0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
167d0 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
167e0 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
167f0 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
16800 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
16810 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
16820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16830 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
16840 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16850 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
16860 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16870 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
16880 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
16890 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
168a0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
168b0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
168c0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
168d0 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
168e0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
168f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
16900 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
16910 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
16920 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16930 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
16940 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16950 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
16960 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
16970 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
16980 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
16990 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
169a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
169b0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
169c0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
169d0 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
169e0 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
169f0 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
16a00 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
16a10 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
16a20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
16a30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
16a40 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
16a50 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
16a60 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
16a70 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16a80 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
16a90 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
16aa0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
16ab0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
16ac0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
16ad0 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
16ae0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
16af0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
16b00 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
16b10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
16b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
16b30 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16b40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
16b50 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
16b60 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
16b70 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
16b80 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
16b90 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
16ba0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
16bb0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
16bc0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16bd0 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
16be0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16bf0 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
16c00 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
16c10 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
16c20 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
16c30 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
16c40 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16c50 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
16c60 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
16c70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
16c80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16c90 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
16ca0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
16cb0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
16cc0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
16cd0 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
16ce0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
16cf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16d00 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
16d10 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
16d20 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
16d30 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
16d40 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
16d50 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
16d60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16d70 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16d80 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
16d90 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16da0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
16db0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16dc0 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
16dd0 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
16de0 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
16df0 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
16e00 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
16e10 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
16e20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16e30 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
16e40 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
16e50 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16e60 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
16e70 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
16e80 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
16e90 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
16ea0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
16eb0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
16ec0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
16ed0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
16ee0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
16ef0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
16f00 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
16f10 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
16f20 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
16f30 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16f40 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
16f50 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
16f60 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
16f70 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
16f80 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
16f90 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
16fa0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
16fb0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16fc0 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16fd0 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16fe0 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16ff0 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
17000 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
17010 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
17020 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
17030 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
17040 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
17050 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
17060 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17070 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17080 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
17090 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
170a0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
170b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
170c0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
170d0 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
170e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
170f0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
17100 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
17110 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
17120 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
17130 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
17140 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
17150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17160 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
17170 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
17180 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
17190 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
171a0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
171b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
171c0 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
171d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
171e0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
171f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17200 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17210 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
17220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17230 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
17240 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17250 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17260 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
17270 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
17280 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
17290 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
172a0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
172b0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
172c0 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
172d0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
172e0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
172f0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
17300 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
17310 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
17320 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
17330 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
17340 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
17350 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
17360 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
17370 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17380 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
17390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
173a0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
173b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
173c0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
173d0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
173e0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
173f0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
17400 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
17410 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
17420 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
17430 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
17440 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
17450 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
17460 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
17470 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
17480 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
17490 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
174a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
174b0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
174c0 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
174d0 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
174e0 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
174f0 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
17500 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
17510 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
17520 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
17530 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
17540 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
17550 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
17560 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
17570 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
17580 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
17590 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
175a0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
175b0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
175c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
175d0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
175e0 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
175f0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17600 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
17610 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17620 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17630 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17640 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17650 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
17660 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
17670 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
17680 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
17690 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
176a0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
176b0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
176c0 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
176d0 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
176e0 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
176f0 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
17700 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
17710 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
17720 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
17730 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
17740 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
17750 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
17760 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
17770 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
17780 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
17790 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
177a0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
177b0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
177c0 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
177d0 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
177e0 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
177f0 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
17800 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
17810 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
17820 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
17830 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
17840 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
17850 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
17860 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
17870 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
17880 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
17890 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
178a0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
178b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
178c0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
178d0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
178e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
178f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
17900 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
17910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17920 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
17930 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
17940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17950 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
17960 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
17970 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
17980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17990 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
179a0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
179b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
179c0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
179d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
179e0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
179f0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
17a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
17a20 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
17a30 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
17a40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a50 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
17a60 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
17a70 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
17a80 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
17a90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17aa0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
17ab0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
17ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ad0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
17ae0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
17af0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
17b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17b10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
17b20 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
17b30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
17b40 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
17b50 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
17b60 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
17b70 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
17b80 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
17b90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ba0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
17bb0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
17bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17bd0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
17be0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
17bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17c10 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
17c20 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
17c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17c40 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
17c50 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
17c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17c70 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
17c80 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ca0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17cb0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17cc0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17cd0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17cf0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17d00 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17d10 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17d30 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17d40 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
17d50 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17d60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
17d70 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
17d80 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17da0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17db0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17dc0 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17dd0 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17df0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17e00 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17e10 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17e20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17e30 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
17e40 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
17e50 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
17e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
17e70 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
17e80 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17e90 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17eb0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17ec0 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17ed0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
17ee0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ef0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20  _SMALL_MALLOC   
17f00 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c       27  /* bool
17f10 65 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ean */../*.** CA
17f20 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
17f30 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
17f40 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
17f50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
17f60 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
17f70 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
17f80 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
17f90 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
17fa0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
17fb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17fc0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
17fd0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17fe0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
17ff0 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
18000 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
18010 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
18020 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
18030 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
18040 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
18050 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
18060 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
18070 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
18080 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
18090 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
180a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
180b0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
180c0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
180d0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
180e0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
180f0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
18100 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
18110 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
18120 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
18130 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
18140 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
18150 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18160 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
18170 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
18180 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18190 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
181a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
181b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
181c0 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
181d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
181e0 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
181f0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
18200 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
18210 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
18220 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18230 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
18240 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18250 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
18260 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
18270 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
18280 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
18290 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
182a0 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
182b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
182c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
182d0 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
182e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
182f0 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
18300 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
18310 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
18320 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
18330 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
18340 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
18350 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
18360 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
18370 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
18380 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
18390 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
183a0 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
183b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
183c0 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
183d0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
183e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
183f0 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
18400 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
18410 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
18420 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
18430 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
18440 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
18450 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
18460 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
18470 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
18480 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
18490 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
184a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
184b0 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
184c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
184d0 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
184e0 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
184f0 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
18500 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
18510 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
18520 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
18530 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18540 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
18550 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
18560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
18570 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
18580 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
18590 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
185a0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
185b0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
185c0 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
185d0 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
185e0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
185f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
18600 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
18610 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
18620 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
18630 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
18640 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
18650 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
18660 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
18670 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
18680 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
18690 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
186a0 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
186b0 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
186c0 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
186d0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
186e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
186f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18700 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
18710 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18720 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18730 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18740 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
18750 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
18760 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
18770 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
18780 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18790 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
187a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
187b0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
187c0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
187d0 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
187e0 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
187f0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
18800 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
18810 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
18820 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
18830 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
18840 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18850 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18860 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
18870 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18880 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18890 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
188a0 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
188b0 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
188c0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
188d0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
188e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
188f0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18900 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18910 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
18920 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
18930 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18940 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
18950 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18960 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
18970 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
18980 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
18990 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
189a0 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
189b0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
189c0 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
189d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
189e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
189f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
18a00 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
18a10 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
18a20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18a30 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
18a40 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18a50 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
18a60 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
18a70 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
18a80 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
18a90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18ab0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18ac0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18ad0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18ae0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
18af0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
18b00 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18b10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18b20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18b30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18b40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18b50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18b60 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
18b70 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18b80 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18b90 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18ba0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18bb0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
18bc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
18bd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18be0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18bf0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77  r disable the tw
18c00 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65  o-argument.** ve
18c10 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74  rsion of the [ft
18c20 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20  s3_tokenizer()] 
18c30 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69  function which i
18c40 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
18c50 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78   [FTS3] full-tex
18c60 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20  t search engine 
18c70 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68  extension..** Th
18c80 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18c90 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18ca0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18cb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18cc0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18cd0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18ce0 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18cf0 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76  () or.** positiv
18d00 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33  e to enable fts3
18d10 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20  _tokenizer() or 
18d20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
18d30 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  e the setting.**
18d40 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
18d50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18d60 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18d70 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
18d80 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18d90 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18da0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18db0 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  er fts3_tokenize
18dc0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  r is disabled or
18dd0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
18de0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18df0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18e00 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
18e10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18e20 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18e30 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
18e40 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18e50 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18e60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18e70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
18e80 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
18e90 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18ea0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18eb0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18ec0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
18ed0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18ee0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
18ef0 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
18f00 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
18f10 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
18f20 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
18f30 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
18f40 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
18f50 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18f60 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
18f70 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
18f80 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18f90 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
18fa0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
18fb0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
18fc0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18fd0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18fe0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
18ff0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
19000 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
19010 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
19020 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
19030 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
19040 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19050 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
19060 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
19070 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
19080 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
19090 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
190a0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
190b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
190c0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
190d0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
190e0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
190f0 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
19100 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
19110 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
19120 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
19130 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
19140 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19150 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19160 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
19170 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
19180 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19190 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
191a0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
191b0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
191c0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
191d0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
191e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
191f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
19200 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
19210 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
19220 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
19230 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
19240 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19250 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
19260 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
19280 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20  NDBNAME</dt>.** 
19290 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
192a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61  n is used to cha
192b0 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nge the name of 
192c0 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62  the "main" datab
192d0 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20  ase.** schema.  
192e0 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65  ^The sole argume
192f0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
19300 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54  to a constant UT
19310 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69  F8 string.** whi
19320 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ch will become t
19330 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61  he new schema na
19340 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  me in place of "
19350 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a  main".  ^SQLite.
19360 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65  ** does not make
19370 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e   a copy of the n
19380 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e  ew main schema n
19390 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74  ame string, so t
193a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
193b0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
193c0 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  at the argument 
193d0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73  passed into this
193e0 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e   DBCONFIG option
193f0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a   is unchanged.**
19400 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
19410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19420 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
19430 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19440 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19450 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
19460 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73  </dt>.** <dd> Us
19470 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61  ually, when a da
19480 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f  tabase in wal mo
19490 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  de is closed or 
194a0 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20  detached from a 
194b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
194c0 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63  dle, SQLite chec
194d0 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20  ks if this will 
194e0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20  mean that there 
194f0 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63  are now no .** c
19500 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c  onnections at al
19510 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  l to the databas
19520 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72  e. If so, it per
19530 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69  forms a checkpoi
19540 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  nt .** operation
19550 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20   before closing 
19560 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
19570 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20  This option may 
19580 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76  be used to.** ov
19590 65 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61  erride this beha
195a0 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74  viour. The first
195b0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
195c0 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74  d to this operat
195d0 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ion.** is an int
195e0 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20  eger - non-zero 
195f0 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b  to disable check
19600 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c  points-on-close,
19610 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a   or zero (the.**
19620 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61   default) to ena
19630 62 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65  ble them. The se
19640 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19650 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19660 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74  n integer.** int
19670 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74  o which is writt
19680 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19690 69 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68  icate whether ch
196a0 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
196b0 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  se.** have been 
196c0 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20  disabled - 0 if 
196d0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73  they are not dis
196e0 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79  abled, 1 if they
196f0 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   are..** </dd>.*
19700 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19710 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
19720 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28  G</dt>.** <dd>^(
19730 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  The SQLITE_DBCON
19740 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
19750 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
19760 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
19770 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c  ** the [query pl
19780 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20  anner stability 
19790 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47  guarantee] (QPSG
197a0 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53  ).  When the QPS
197b0 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20  G is active,.** 
197c0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
197d0 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ry statement wil
197e0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
197f0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
19800 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
19810 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e   values of [boun
19820 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e  d parameters].)^
19830 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c   The QPSG disabl
19840 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70  es some query op
19850 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74  timizations.** t
19860 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20  hat look at the 
19870 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20  values of bound 
19880 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63  parameters, whic
19890 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20  h can make some 
198a0 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65  queries.** slowe
198b0 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47  r.  But the QPSG
198c0 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61   has the advanta
198d0 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69  ge of more predi
198e0 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ctable behavior.
198f0 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50    With.** the QP
19900 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74  SG active, SQLit
19910 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  e will always us
19920 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79  e the same query
19930 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65   plan in the fie
19940 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65  ld as.** was use
19950 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
19960 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20   in the lab..** 
19970 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c  </dd>.** <dt>SQL
19980 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49  ITE_DBCONFIG_TRI
19990 47 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a  GGER_EQP</dt>.**
199a0 20 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c 74   <dd> By default
199b0 2c 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  , the output of 
199c0 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c  EXPLAIN QUERY PL
199d0 41 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73  AN commands does
199e0 20 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65   not .** include
199f0 20 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79 20   output for any 
19a00 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f  operations perfo
19a10 72 6d 65 64 20 62 79 20 74 72 69 67 67 65 72 20  rmed by trigger 
19a20 70 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a  programs. This.*
19a30 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
19a40 20 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72   to set or clear
19a50 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 20 61   (the default) a
19a60 20 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65 72   flag that gover
19a70 6e 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61 76  ns this.** behav
19a80 69 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  ior. The first p
19a90 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
19aa0 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
19ab0 6e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  n is an integer 
19ac0 2d 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f  -.** non-zero to
19ad0 20 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20 66   enable output f
19ae0 6f 72 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  or trigger progr
19af0 61 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20  ams, or zero to 
19b00 64 69 73 61 62 6c 65 20 69 74 2e 0a 2a 2a 20 54  disable it..** T
19b10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19b20 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
19b30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
19b40 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
19b50 74 74 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20  tten .** 0 or 1 
19b60 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19b70 68 65 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74  her output-for-t
19b80 72 69 67 67 65 72 73 20 68 61 73 20 62 65 65 6e  riggers has been
19b90 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66   disabled - 0 if
19ba0 20 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64   .** it is not d
19bb0 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74  isabled, 1 if it
19bc0 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a   is.  .** </dd>.
19bd0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
19be0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19bf0 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
19c00 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
19c10 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19c30 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19c40 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
19c50 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
19c60 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
19c70 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19c80 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
19c90 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
19ca0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19cb0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19cc0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
19cd0 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
19ce0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19cf0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19d00 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
19d10 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
19d20 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19d40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
19d50 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
19d60 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19d80 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
19d90 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30  ON_CLOSE      10
19da0 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  06 /* int int* *
19db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19dc0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19dd0 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20  _QPSG           
19de0 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1007 /* int int*
19df0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19e00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47  TE_DBCONFIG_TRIG
19e10 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20  GER_EQP         
19e20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e    1008 /* int in
19e30 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19e40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
19e50 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  X               
19e60 20 20 20 20 31 30 30 38 20 2f 2a 20 4c 61 72 67      1008 /* Larg
19e70 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a  est DBCONFIG */.
19e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19e90 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
19ea0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
19eb0 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
19ec0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19ed0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
19ee0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
19ef0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
19f00 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
19f10 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
19f20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
19f30 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
19f40 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
19f50 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
19f60 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
19f70 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
19f80 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
19f90 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
19fa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
19fb0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19fc0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
19fd0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
19fe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19ff0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1a000 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1a010 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
1a020 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
1a030 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
1a040 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
1a050 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
1a060 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
1a070 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1a080 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1a090 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1a0a0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1a0b0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1a0c0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1a0d0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1a0e0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1a0f0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1a100 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1a110 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1a120 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1a130 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1a140 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1a150 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1a160 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1a170 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1a180 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1a190 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1a1a0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1a1b0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1a1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a1d0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a1e0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1a1f0 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
1a200 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
1a210 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
1a220 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
1a230 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
1a240 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
1a250 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
1a260 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
1a270 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
1a280 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
1a290 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
1a2a0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
1a2b0 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
1a2c0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
1a2d0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1a2e0 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
1a2f0 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
1a300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a310 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
1a320 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a330 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1a340 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
1a350 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
1a360 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
1a370 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
1a380 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
1a390 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
1a3a0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a3b0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1a3c0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
1a3d0 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
1a3e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
1a3f0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a400 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
1a410 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1a420 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
1a430 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
1a440 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
1a450 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
1a460 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
1a470 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
1a480 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
1a490 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
1a4a0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
1a4b0 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
1a4c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
1a4d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a4e0 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
1a4f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1a500 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
1a510 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
1a520 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
1a530 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
1a540 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
1a550 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1a560 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
1a570 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
1a580 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
1a590 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
1a5a0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
1a5b0 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
1a5c0 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
1a5d0 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
1a5e0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a5f0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
1a600 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
1a610 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
1a620 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
1a630 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1a640 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1a650 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
1a660 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
1a670 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
1a680 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
1a690 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
1a6a0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
1a6b0 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
1a6c0 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
1a6d0 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
1a6e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a6f0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1a700 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1a710 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1a720 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1a730 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
1a740 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1a750 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1a760 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1a770 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1a780 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1a790 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1a7a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1a7b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a7c0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1a7d0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1a7e0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1a7f0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1a800 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1a810 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1a820 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a830 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a840 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a850 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a860 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a870 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a880 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a890 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a8a0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a8b0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a8c0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a8d0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a8e0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a8f0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a900 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a910 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a920 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a930 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a940 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a950 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a960 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a970 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a980 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a990 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a9a0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a9b0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a9c0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a9d0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a9e0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a9f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1aa00 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1aa10 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1aa20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1aa30 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1aa40 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1aa50 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1aa60 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1aa70 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1aa80 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1aa90 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1aaa0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1aab0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1aac0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1aad0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1aae0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1aaf0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1ab00 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1ab10 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1ab20 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1ab30 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1ab40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1ab50 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1ab60 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1ab70 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1ab80 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1ab90 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1aba0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1abb0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
1abc0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1abd0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
1abe0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1abf0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1ac00 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20  PI3REF: Set the 
1ac10 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1ac20 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48  d value..** METH
1ac30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ac40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65  * The sqlite3_se
1ac50 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1ac60 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64  wid(D, R) method
1ac70 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c   allows the appl
1ac80 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65  ication to.** se
1ac90 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1aca0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  rned by calling 
1acb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1acc0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20  ert_rowid(D) to 
1acd0 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e  R .** without in
1ace0 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e  serting a row in
1acf0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
1ad00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1ad10 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
1ad20 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1ad30 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
1ad40 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
1ad50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
1ad60 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
1ad70 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1ad80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ad90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1ada0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1adb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1adc0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1add0 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1ade0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1adf0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1ae00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1ae10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1ae20 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1ae30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ae40 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1ae50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1ae60 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1ae70 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1ae80 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1ae90 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1aea0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1aeb0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1aec0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1aed0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1aee0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1aef0 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1af00 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1af10 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1af20 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1af30 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1af40 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1af50 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1af60 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1af70 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1af80 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1af90 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1afa0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1afb0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1afc0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1afd0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1afe0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1aff0 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1b000 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1b010 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1b020 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1b030 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1b040 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1b050 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1b060 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1b070 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1b080 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1b090 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1b0a0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1b0b0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1b0c0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1b0d0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1b0e0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1b0f0 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1b100 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1b110 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1b120 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1b130 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1b140 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1b150 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1b160 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1b170 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1b180 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b190 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1b1a0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1b1b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1b1c0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1b1d0 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1b1e0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1b1f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1b200 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1b210 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1b220 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1b230 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1b240 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1b250 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1b260 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1b270 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1b280 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1b290 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1b2a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1b2b0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1b2c0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1b2d0 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1b2e0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1b2f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1b300 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1b310 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1b320 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1b330 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1b340 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1b350 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1b360 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1b370 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1b380 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1b390 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1b3a0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1b3b0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1b3c0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1b3d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b3e0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1b3f0 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1b400 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1b410 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1b420 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1b430 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1b440 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1b450 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1b460 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1b470 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1b480 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1b490 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1b4a0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1b4b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1b4c0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1b4d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1b4e0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1b4f0 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1b500 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1b510 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1b520 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1b530 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1b540 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1b550 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1b560 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1b570 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b580 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1b590 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1b5a0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1b5b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1b5c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b5d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b5e0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1b5f0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1b600 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1b610 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b620 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1b630 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1b640 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1b650 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1b660 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b670 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b680 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1b690 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1b6a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1b6b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1b6c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1b6d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1b6e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1b6f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1b700 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b710 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1b720 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
1b730 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61   int sqlite3_cha
1b740 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1b750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b760 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1b770 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1b780 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b790 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1b7a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1b7b0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1b7c0 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1b7d0 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1b7e0 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1b7f0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1b800 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1b810 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1b820 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1b830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b840 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1b850 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1b860 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1b870 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1b880 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1b890 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1b8a0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1b8b0 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1b8c0 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1b8d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1b8e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1b8f0 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1b900 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1b910 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1b920 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1b930 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1b940 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1b950 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1b960 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1b970 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1b980 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1b990 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1b9a0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1b9b0 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1b9c0 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1b9d0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1b9e0 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
1b9f0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1ba00 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1ba10 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1ba20 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1ba30 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
1ba40 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
1ba50 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1ba60 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1ba70 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1ba80 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1ba90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1baa0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1bab0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1bac0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1bad0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1bae0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1baf0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1bb00 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1bb10 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1bb20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  I int sqlite3_to
1bb30 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
1bb40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1bb50 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
1bb60 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
1bb70 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44   Query.** METHOD
1bb80 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1bb90 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
1bba0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
1bbb0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
1bbc0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
1bbd0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
1bbe0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
1bbf0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
1bc00 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
1bc10 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
1bc20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
1bc30 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
1bc40 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
1bc50 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
1bc60 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
1bc70 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
1bc80 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
1bc90 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
1bca0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
1bcb0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
1bcc0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
1bcd0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
1bce0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
1bcf0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
1bd00 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1bd10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
1bd20 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
1bd30 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
1bd40 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1bd50 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
1bd60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bd70 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
1bd80 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
1bd90 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
1bda0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
1bdb0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
1bdc0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
1bdd0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
1bde0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
1bdf0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
1be00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1be10 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
1be20 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
1be30 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
1be40 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
1be50 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
1be60 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
1be70 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
1be80 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
1be90 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
1bea0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
1beb0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
1bec0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
1bed0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
1bee0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1bef0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1bf00 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1bf10 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
1bf20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1bf30 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
1bf40 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
1bf50 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
1bf60 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
1bf70 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
1bf80 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1bf90 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
1bfa0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
1bfb0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
1bfc0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1bfd0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
1bfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bff0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
1c000 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
1c010 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1c020 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1c030 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1c040 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
1c050 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
1c060 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1c070 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
1c080 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
1c090 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
1c0a0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
1c0b0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
1c0c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c0d0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
1c0e0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1c0f0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1c100 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
1c110 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
1c120 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1c130 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
1c140 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
1c150 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
1c160 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
1c170 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1c180 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
1c190 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
1c1a0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1c1b0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
1c1c0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
1c1d0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
1c1e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1c1f0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1c200 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1c210 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
1c220 65 74 75 72 6e 73 2e 0a 2a 2f 0a 53 51 4c 49 54  eturns..*/.SQLIT
1c230 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1c240 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1c250 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1c260 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1c270 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1c280 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1c290 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1c2a0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1c2b0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1c2c0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1c2d0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1c2e0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1c2f0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1c300 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1c310 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1c320 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1c330 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1c340 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1c350 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1c360 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1c370 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1c380 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1c390 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1c3a0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1c3b0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1c3c0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1c3d0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1c3e0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1c3f0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1c400 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1c410 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1c420 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1c430 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1c440 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1c450 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1c460 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1c470 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1c480 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1c490 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1c4a0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1c4b0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1c4c0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1c4d0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1c4e0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1c4f0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1c500 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1c510 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1c520 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1c530 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1c540 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1c550 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1c560 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1c570 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1c580 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1c590 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1c5a0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1c5b0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1c5c0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1c5d0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1c5e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c5f0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1c600 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1c610 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1c620 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1c630 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1c640 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1c650 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1c660 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1c670 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1c680 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1c690 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1c6a0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1c6b0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1c6c0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1c6d0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1c6e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1c6f0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1c700 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1c710 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1c720 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1c730 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c740 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1c750 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1c760 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1c770 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1c780 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c790 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1c7a0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1c7b0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1c7c0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1c7d0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1c7e0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1c7f0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1c800 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1c810 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1c820 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1c830 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1c840 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1c850 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1c860 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1c870 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1c880 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1c890 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1c8a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1c8b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1c8c0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1c8d0 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
1c8e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1c8f0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1c900 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1c910 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1c920 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1c930 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1c940 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1c950 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1c960 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1c970 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1c980 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c990 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1c9a0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c9b0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1c9c0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1c9d0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1c9e0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1c9f0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1ca00 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1ca10 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1ca20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1ca30 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1ca40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1ca50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ca60 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1ca70 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1ca80 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1ca90 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1caa0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1cab0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1cac0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1cad0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1cae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1caf0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1cb00 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cb10 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1cb20 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1cb30 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1cb40 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1cb50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1cb60 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1cb70 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1cb80 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1cb90 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1cba0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1cbb0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1cbc0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1cbd0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1cbe0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1cbf0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1cc00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cc10 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1cc20 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1cc30 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1cc40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1cc50 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1cc60 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1cc70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1cc80 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1cc90 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1cca0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1ccb0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1ccc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1ccd0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1cce0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1ccf0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1cd00 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1cd10 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1cd20 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1cd30 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1cd40 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1cd50 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1cd60 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1cd70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1cd80 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1cd90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cda0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1cdb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1cdc0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1cdd0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1cde0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1cdf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1ce00 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1ce10 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1ce20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1ce30 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1ce40 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1ce50 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1ce60 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1ce70 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1ce80 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1ce90 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1cea0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1ceb0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1cec0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1ced0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1cee0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1cef0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1cf00 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1cf10 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1cf20 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1cf30 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1cf40 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1cf50 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1cf60 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1cf70 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1cf80 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1cf90 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1cfa0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1cfb0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1cfc0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1cfd0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1cfe0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1cff0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1d000 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1d010 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1d020 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1d030 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1d040 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1d050 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1d060 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1d070 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1d080 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1d090 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1d0a0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1d0b0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1d0c0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1d0d0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1d0e0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1d0f0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1d100 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1d110 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1d120 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1d130 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1d140 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1d150 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1d160 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1d170 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1d180 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1d190 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1d1a0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1d1b0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1d1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1d1d0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1d1e0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1d1f0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1d200 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1d210 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1d220 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1d230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d240 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1d250 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1d260 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1d270 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1d280 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1d290 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1d2a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1d2b0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1d2c0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1d2d0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1d2e0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1d2f0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1d300 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1d310 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1d320 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1d330 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1d340 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1d350 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1d360 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1d370 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1d380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1d390 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1d3a0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1d3b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1d3c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d3d0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1d3e0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1d3f0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1d400 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1d410 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1d420 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1d430 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1d440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d450 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1d460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1d470 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1d480 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1d490 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d4a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d4b0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1d4c0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1d4d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d4e0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1d4f0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1d500 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d510 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1d520 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1d530 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1d540 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1d550 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1d560 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1d570 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1d580 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1d590 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1d5a0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1d5b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1d5c0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1d5d0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1d5e0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1d5f0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1d600 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1d610 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1d620 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1d630 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1d640 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1d650 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1d660 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1d670 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1d680 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1d690 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1d6a0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1d6b0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1d6c0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1d6d0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1d6e0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1d6f0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1d700 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1d710 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1d720 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1d730 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d740 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1d750 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1d760 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1d770 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1d780 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1d790 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d7a0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1d7b0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1d7c0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1d7d0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1d7e0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1d7f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1d800 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1d810 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  out].*/.SQLITE_A
1d820 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1d830 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1d840 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1d850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d860 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1d870 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1d880 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1d890 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1d8a0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1d8b0 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1d8c0 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1d8d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1d8e0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1d8f0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1d900 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1d910 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1d920 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1d930 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1d940 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1d950 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1d960 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1d970 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d980 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1d990 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1d9a0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1d9b0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1d9c0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1d9d0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1d9e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1d9f0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1da00 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1da10 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1da20 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1da30 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1da40 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1da50 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1da60 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1da70 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1da80 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1da90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1daa0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1dab0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1dac0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1dad0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1dae0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1daf0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1db00 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1db10 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1db20 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1db30 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1db40 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1db50 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1db60 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1db70 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1db80 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1db90 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1dba0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1dbb0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1dbc0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1dbd0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1dbe0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1dbf0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1dc00 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1dc10 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1dc20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1dc30 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1dc40 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1dc50 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1dc60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1dc70 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1dc80 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1dc90 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1dca0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1dcb0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1dcc0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1dcd0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1dce0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1dcf0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1dd00 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1dd10 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1dd20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1dd30 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1dd40 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1dd50 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1dd60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1dd70 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1dd80 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1dd90 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1dda0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ddb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ddc0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1ddd0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1dde0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1ddf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1de00 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1de10 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1de20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1de30 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1de40 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1de50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1de60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1de70 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1de80 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1de90 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1dea0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1deb0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1dec0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1ded0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1dee0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1def0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1df00 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1df10 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1df20 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1df30 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1df40 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1df50 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1df60 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1df70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1df80 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1df90 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dfa0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1dfb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1dfc0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1dfd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1dfe0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1dff0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1e000 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1e010 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1e020 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1e030 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1e040 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e050 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1e060 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e070 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1e080 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e090 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1e0a0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1e0b0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1e0c0 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1e0d0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1e0e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e0f0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1e100 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1e110 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1e120 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1e130 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1e140 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1e150 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1e160 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1e170 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1e180 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1e190 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1e1a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e1b0 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1e1c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1e1d0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1e1e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1e1f0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1e200 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1e210 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1e220 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1e230 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1e240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1e250 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1e260 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1e270 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1e280 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1e290 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1e2a0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1e2b0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1e2c0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1e2d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1e2e0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1e2f0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1e300 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1e310 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1e320 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1e330 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1e340 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1e350 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1e360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1e370 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1e380 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1e390 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1e3a0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1e3b0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1e3c0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1e3d0 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1e3e0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1e3f0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1e400 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1e410 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1e420 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1e430 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1e440 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1e450 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1e460 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1e470 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1e480 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1e490 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1e4a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1e4b0 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1e4c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1e4d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1e4e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1e4f0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1e500 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1e510 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1e520 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1e530 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1e540 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1e550 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1e560 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1e570 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1e580 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1e590 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1e5a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e5b0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1e5c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1e5d0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1e5e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1e5f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1e600 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1e610 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1e620 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1e630 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1e640 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
1e650 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1e660 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1e670 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1e680 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1e690 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1e6a0 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1e6b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1e6c0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1e6d0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1e6e0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1e6f0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1e700 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1e710 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
1e720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64  ese routines und
1e730 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20  erstand most of 
1e740 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66  the common K&R f
1e750 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e760 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  s,.** plus some 
1e770 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1e780 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c  tandard formats,
1e790 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e   detailed below.
1e7a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f  .** Note that so
1e7b0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f  me of the more o
1e7c0 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e  bscure formattin
1e7d0 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72  g options from r
1e7e0 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61  ecent.** C-libra
1e7f0 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65  ry standards are
1e800 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1e810 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  is implementatio
1e820 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
1e830 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1e840 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1e850 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1e860 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1e870 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1e880 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1e890 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e8a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1e8b0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1e8c0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1e8d0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1e8e0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1e8f0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1e900 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1e910 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1e920 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1e930 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1e940 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1e950 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1e960 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1e970 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1e980 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1e990 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e9a0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1e9b0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1e9c0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1e9d0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1e9e0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1e9f0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1ea00 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1ea10 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1ea20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1ea30 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1ea40 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1ea50 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1ea60 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1ea70 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1ea80 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1ea90 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1eaa0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1eab0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1eac0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1ead0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1eae0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1eaf0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1eb00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1eb10 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1eb20 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1eb30 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1eb40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1eb50 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1eb60 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1eb70 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1eb80 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1eb90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1eba0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1ebb0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1ebc0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1ebd0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1ebe0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1ebf0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1ec00 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1ec10 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1ec20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1ec30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1ec40 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1ec50 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1ec60 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1ec70 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1ec80 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1ec90 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1eca0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ecb0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1ecc0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1ecd0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1ece0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1ecf0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1ed00 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1ed10 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1ed20 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1ed30 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1ed40 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1ed50 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1ed60 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1ed70 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1ed80 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1ed90 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1eda0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1edb0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1edc0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1edd0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1ede0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1edf0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1ee00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1ee10 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1ee20 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1ee30 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1ee40 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1ee50 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1ee60 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1ee70 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1ee80 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1ee90 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1eea0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1eeb0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1eec0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1eed0 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a  Q", "%w" and "%z
1eee0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1eef0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1ef00 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1ef10 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1ef20 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1ef30 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1ef40 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1ef50 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1ef60 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1ef70 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1ef80 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1ef90 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1efa0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1efb0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1efc0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1efd0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1efe0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1eff0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1f000 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1f010 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1f020 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1f030 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1f040 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1f050 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1f060 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1f070 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1f080 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1f090 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1f0a0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1f0b0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1f0c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f0d0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1f0e0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1f0f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1f100 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1f110 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1f120 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1f130 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1f140 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1f150 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1f160 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1f170 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1f180 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1f190 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1f1a0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1f1b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f1c0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1f1d0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1f1e0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1f1f0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1f200 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1f210 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1f220 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1f230 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1f240 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1f250 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1f260 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1f270 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1f280 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1f290 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1f2a0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1f2b0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1f2c0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1f2d0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1f2e0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1f2f0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1f300 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1f310 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f320 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1f330 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1f340 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1f350 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f360 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f370 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1f380 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1f390 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1f3a0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1f3b0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1f3c0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1f3d0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1f3e0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1f3f0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1f400 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1f410 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1f420 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1f430 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1f440 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1f450 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1f460 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1f470 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1f480 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1f490 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1f4a0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1f4b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1f4c0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1f4d0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1f4e0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1f4f0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1f500 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1f510 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1f520 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1f530 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1f540 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1f550 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1f560 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1f570 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1f580 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1f590 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1f5a0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1f5b0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1f5c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1f5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1f5e0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1f5f0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1f600 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1f610 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1f620 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1f630 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1f640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f650 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22  **.** ^(The "%w"
1f660 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f670 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20  on is like "%q" 
1f680 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65  except that it e
1f690 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20  xpects to.** be 
1f6a0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1f6b0 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69   double-quotes i
1f6c0 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65  nstead of single
1f6d0 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a   quotes, and it.
1f6e0 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64  ** escapes the d
1f6f0 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72  ouble-quote char
1f700 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  acter instead of
1f710 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74   the single-quot
1f720 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29  e.** character.)
1f730 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d  ^  The "%w" form
1f740 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1f750 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61   intended for sa
1f760 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a  fely inserting.*
1f770 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  * table and colu
1f780 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20  mn names into a 
1f790 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20  constructed SQL 
1f7a0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1f7b0 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1f7c0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1f7d0 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1f7e0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1f7f0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1f800 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1f810 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1f820 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1f830 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1f840 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1f850 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1f860 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1f870 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1f880 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f890 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1f8a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f8b0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1f8c0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1f8d0 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1f8e0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1f8f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1f900 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f910 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1f920 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1f930 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f940 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f950 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f970 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f980 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f990 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f9a0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f9b0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f9c0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f9d0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f9e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f9f0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1fa00 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1fa10 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1fa20 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1fa30 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1fa40 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1fa50 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1fa60 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1fa70 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1fa80 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1fa90 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1faa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fab0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1fac0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1fad0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1fae0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1faf0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1fb00 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1fb10 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1fb20 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1fb30 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1fb40 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1fb50 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1fb60 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1fb70 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1fb80 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1fb90 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1fba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1fbb0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1fbc0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1fbd0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1fbe0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1fbf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1fc00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1fc10 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1fc20 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1fc30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1fc40 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1fc50 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1fc60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1fc70 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1fc80 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1fc90 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1fca0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1fcb0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1fcc0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1fcd0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1fce0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1fcf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fd00 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1fd10 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1fd20 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1fd30 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1fd40 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1fd50 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1fd60 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1fd70 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1fd80 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1fd90 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1fda0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1fdb0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1fdc0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1fdd0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1fde0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1fdf0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1fe00 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1fe10 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1fe20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1fe30 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1fe40 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1fe50 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1fe60 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1fe70 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1fe80 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1fe90 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fea0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1feb0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1fec0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1fed0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1fee0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1fef0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1ff00 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ff10 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ff20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1ff30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ff40 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1ff50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1ff60 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1ff70 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1ff80 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1ff90 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ffa0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1ffb0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1ffc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ffd0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1ffe0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1fff0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
20000 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
20010 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
20020 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
20030 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
20040 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20050 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
20060 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
20070 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
20080 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
20090 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
200a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
200b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
200c0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
200d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
200e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
200f0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
20100 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
20110 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
20120 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
20130 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
20140 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
20150 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
20160 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
20170 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
20180 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
20190 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
201a0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
201b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
201c0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
201d0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
201e0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
201f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
20200 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
20210 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
20220 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
20230 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
20240 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
20250 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
20260 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
20270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20280 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
20290 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
202a0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
202b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
202c0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
202d0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
202e0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
202f0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
20300 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
20310 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
20320 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
20330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
20340 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
20350 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
20360 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
20370 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
20380 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20390 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
203a0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
203b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
203c0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
203d0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
203e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
203f0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
20400 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
20410 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
20420 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
20430 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
20440 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
20450 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
20460 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
20470 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
20480 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
20490 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
204a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
204b0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
204c0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
204d0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
204e0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
204f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
20500 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
20510 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
20520 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
20530 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
20540 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
20550 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20560 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
20570 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
20580 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
20590 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
205a0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
205b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
205c0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
205d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
205e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
205f0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
20600 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
20610 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
20620 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
20630 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
20640 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
20650 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
20660 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
20670 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
20680 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
20690 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
206a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
206b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
206c0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
206d0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
206e0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
206f0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
20700 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
20710 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
20720 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
20730 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
20740 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
20750 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
20760 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
20770 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
20780 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
20790 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
207a0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
207b0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
207c0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
207d0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
207e0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
207f0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
20800 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
20810 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
20820 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
20830 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
20840 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
20850 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
20860 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
20870 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
20880 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
20890 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
208a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
208b0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
208c0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
208d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
208e0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
208f0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
20900 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
20910 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
20920 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
20930 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
20940 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
20950 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
20960 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
20970 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
20980 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
20990 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
209a0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
209b0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
209c0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
209d0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
209e0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
209f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20a00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20a10 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
20a20 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
20a30 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
20a40 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
20a50 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
20a60 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
20a70 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
20a80 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
20a90 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
20aa0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
20ab0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
20ac0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
20ad0 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
20ae0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
20af0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
20b00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
20b10 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  *sqlite3_malloc6
20b20 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
20b30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
20b40 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
20b50 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
20b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20b70 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
20b80 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
20b90 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
20ba0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
20bb0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
20bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
20bd0 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
20be0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
20bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20c00 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
20c10 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
20c20 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
20c30 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
20c40 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
20c50 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
20c60 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
20c70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20c80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
20c90 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
20ca0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
20cb0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
20cc0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
20cd0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20ce0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
20cf0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
20d00 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20d10 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20d20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20d30 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
20d40 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
20d50 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
20d60 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
20d70 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
20d80 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20d90 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
20da0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
20db0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
20dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20dd0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
20de0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20df0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
20e00 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
20e10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
20e20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20e30 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
20e40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20e50 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
20e60 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
20e70 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
20e80 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
20e90 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
20ea0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
20eb0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
20ec0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
20ed0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
20ee0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
20ef0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
20f00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20f10 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
20f20 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
20f30 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
20f40 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
20f50 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
20f60 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20f70 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
20f80 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
20f90 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
20fa0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20fb0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
20fc0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
20fd0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
20fe0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20ff0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
21000 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
21010 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
21020 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
21030 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
21040 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
21050 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
21060 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
21070 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
21080 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21090 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
210a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
210b0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
210c0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
210d0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
210e0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
210f0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
21100 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
21110 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
21120 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
21130 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
21140 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
21150 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
21160 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
21170 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
21180 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
21190 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
211a0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
211b0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
211c0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
211d0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
211e0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
211f0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
21200 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
21210 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
21220 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
21230 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
21240 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
21250 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
21260 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
21270 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
21280 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
21290 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
212a0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
212b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
212c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
212d0 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
212e0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
212f0 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
21300 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
21310 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
21320 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
21330 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
21340 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
21350 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
21360 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
21370 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
21380 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
21390 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
213a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
213b0 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
213c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
213d0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
213e0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
213f0 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
21400 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
21410 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
21420 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
21430 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
21440 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
21450 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
21460 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
21470 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
21480 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
21490 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
214a0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
214b0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
214c0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
214d0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
214e0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
214f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
21500 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
21510 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21520 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  k}.**.** ^This r
21530 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
21540 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
21550 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
21560 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
21570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21580 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
21590 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
215a0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
215b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
215c0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
215d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
215e0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
215f0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
21600 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
21610 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
21620 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
21640 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
21650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
21660 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
21670 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
21680 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
21690 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20  epare16_v3()].  
216a0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
216b0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
216c0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
216d0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
216e0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
216f0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
21700 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
21710 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21720 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21730 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
21740 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
21750 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
21760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21770 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
21780 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21790 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
217a0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
217b0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
217c0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
217d0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
217e0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
217f0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
21800 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
21810 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
21820 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
21830 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
21840 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
21850 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
21860 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
21870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21880 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
21890 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
218a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
218b0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
218c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
218d0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
218e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
218f0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21900 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
21910 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
21920 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21930 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21940 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
21950 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
21960 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21970 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
21980 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
21990 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
219a0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
219b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
219c0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
219d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
219e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
219f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21a00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
21a10 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21a20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21a30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21a40 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
21a50 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
21a60 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
21a70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
21a80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
21a90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21aa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
21ab0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
21ac0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
21ad0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21ae0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
21af0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21b00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
21b10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21b20 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
21b30 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
21b40 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
21b50 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
21b60 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
21b70 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
21b80 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
21b90 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
21ba0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
21bb0 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c  k are either NUL
21bc0 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65  L pointers or ze
21bd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
21be0 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f  rings.** that co
21bf0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
21c00 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
21c10 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
21c20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41  authorized..** A
21c30 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
21c40 20 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61   always be prepa
21c50 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72  red to encounter
21c60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21c70 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  in any.** of the
21c80 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74   third through t
21c90 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
21ca0 65 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f  ers of the autho
21cb0 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63  rization callbac
21cc0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  k..**.** ^If the
21cd0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
21ce0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
21cf0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21d00 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21d10 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21d20 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
21d30 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
21d40 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
21d50 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
21d60 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
21d70 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
21d80 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
21d90 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
21da0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
21db0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
21dc0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
21dd0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
21de0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
21df0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
21e00 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
21e10 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
21e20 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
21e30 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
21e40 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20  * ^When a table 
21e50 69 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  is referenced by
21e60 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20   a [SELECT] but 
21e70 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  no column values
21e80 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65   are.** extracte
21e90 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c  d from that tabl
21ea0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69  e (for example i
21eb0 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a  n a query like.*
21ec0 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28  * "SELECT count(
21ed0 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68  *) FROM tab") th
21ee0 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52  en the [SQLITE_R
21ef0 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20  EAD] authorizer 
21f00 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69  callback.** is i
21f10 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
21f20 74 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20  that table with 
21f30 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68  a column name th
21f40 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  at is an empty s
21f50 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
21f60 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21f70 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
21f80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21f90 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
21fa0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21fb0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
21fc0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
21fd0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
21fe0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
21ff0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
22000 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
22010 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
22020 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
22030 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
22040 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
22050 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
22060 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
22070 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
22080 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
22090 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
220a0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
220b0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
220c0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
220d0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
220e0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
220f0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
22100 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
22110 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
22120 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
22130 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
22140 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
22150 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
22160 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
22170 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
22180 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
22190 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
221a0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
221b0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
221c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
221d0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
221e0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
221f0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
22200 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
22210 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
22220 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
22230 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
22240 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
22250 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
22260 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
22270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
22280 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
22290 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
222a0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
222b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
222c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
222d0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
222e0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
222f0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
22300 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
22310 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
22320 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
22330 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
22340 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
22350 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
22360 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
22370 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
22380 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
22390 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
223a0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
223b0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
223c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
223d0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
223e0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
223f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22400 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
22410 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
22420 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22430 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
22440 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
22450 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
22460 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22470 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
22480 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
22490 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
224a0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
224b0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
224c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
224d0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
224e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
224f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
22500 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22510 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
22520 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
22530 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
22540 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
22550 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22560 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
22570 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
22580 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
22590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
225a0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
225b0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
225c0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
225d0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
225e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
225f0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
22600 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
22610 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
22620 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
22630 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
22640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22650 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
22660 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
22670 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
22680 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
22690 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
226a0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
226b0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
226c0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
226d0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
226e0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
226f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
22700 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22710 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
22720 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
22730 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22740 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
22750 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
22760 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
22770 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
22780 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
22790 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
227a0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
227b0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
227c0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
227d0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
227e0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
227f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22800 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
22810 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
22820 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
22830 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
22840 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
22850 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
22860 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
22870 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
22880 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
22890 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
228a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
228b0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
228c0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
228d0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
228e0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
228f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
22900 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22910 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
22920 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22930 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
22940 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
22950 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
22960 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
22970 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
22980 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
22990 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
229a0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
229b0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
229c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
229d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
229e0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
229f0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
22a00 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
22a10 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
22a20 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
22a30 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
22a40 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
22a50 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
22a60 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
22a70 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
22a80 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
22a90 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
22aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ab0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
22ac0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
22ad0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
22ae0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
22af0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
22b00 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
22b10 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
22b20 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
22b30 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
22b40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
22b50 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
22b60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
22b70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22b80 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
22b90 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
22ba0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
22bb0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
22bc0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
22bd0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
22be0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
22bf0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
22c00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
22c10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
22c20 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
22c30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
22c40 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
22c50 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
22c60 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
22c70 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
22c80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
22c90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22ca0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
22cb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
22cc0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
22cd0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
22ce0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
22cf0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
22d00 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
22d10 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
22d20 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
22d30 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
22d40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
22d50 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
22d60 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
22d70 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
22d80 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
22d90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
22da0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
22db0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
22dc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
22dd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22de0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22df0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
22e00 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
22e10 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
22e20 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
22e30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22e40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22e50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
22e60 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
22e70 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
22e80 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
22e90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
22ea0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
22eb0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
22ec0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
22ed0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
22ee0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
22ef0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
22f00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22f10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22f20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
22f30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
22f40 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
22f50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22f60 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
22f70 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
22f80 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22f90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22fb0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
22fc0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
22fd0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22fe0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22ff0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23000 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
23010 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
23020 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23030 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23040 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23050 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
23060 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
23070 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23080 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23090 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
230a0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
230b0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
230c0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
230d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
230e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
230f0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
23100 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
23110 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23120 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23130 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
23140 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
23150 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23160 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23170 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23180 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
23190 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
231a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
231b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
231c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
231d0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
231e0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
231f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23200 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23210 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23220 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
23230 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
23240 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23250 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23260 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23270 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
23280 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
23290 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
232a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
232b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
232c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
232d0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
232e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
232f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23310 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
23320 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
23330 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
23340 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23360 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
23370 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
23380 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
23390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
233a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
233b0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
233c0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
233d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
233e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
233f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23400 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
23410 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
23420 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
23430 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23450 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
23460 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
23470 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
23480 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23490 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
234a0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
234b0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
234c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
234d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
234e0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
234f0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
23500 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
23510 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
23520 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
23530 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
23540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23550 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
23560 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
23570 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
23580 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
23590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
235a0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
235b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
235c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
235d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
235e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
235f0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
23600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23620 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
23630 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
23640 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23650 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
23660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23670 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
23680 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
23690 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
236a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
236b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
236c0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
236d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
236e0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
236f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23710 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
23720 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
23730 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
23740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23760 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
23770 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
23780 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
23790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
237a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
237b0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
237c0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
237d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
237e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
237f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23800 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
23810 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
23820 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
23830 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
23840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23850 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
23860 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
23870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
23880 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
23890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
238a0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
238b0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
238c0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
238d0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
238e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
238f0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
23900 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
23910 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
23920 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
23930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
23940 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
23950 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
23960 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
23970 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
23980 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
23990 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
239a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
239b0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
239c0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
239d0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
239e0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
239f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
23a00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
23a10 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
23a20 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
23a30 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
23a40 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
23a50 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
23a60 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
23a70 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
23a80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
23a90 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
23aa0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
23ab0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
23ac0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
23ad0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
23ae0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
23af0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
23b00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23b10 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
23b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23b30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
23b40 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
23b50 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
23b60 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
23b70 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
23b80 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
23b90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
23ba0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23bb0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
23bc0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
23bd0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
23be0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
23bf0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
23c00 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
23c10 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
23c20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23c30 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
23c40 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
23c50 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
23c60 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
23c70 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
23c80 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
23c90 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
23ca0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
23cb0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
23cc0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
23cd0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
23ce0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
23cf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
23d00 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
23d10 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
23d20 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
23d30 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
23d40 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
23d50 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
23d60 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
23d70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
23d80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
23d90 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
23da0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
23db0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
23dc0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
23dd0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
23de0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
23df0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
23e00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
23e10 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
23e20 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
23e30 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
23e40 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
23e50 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
23e60 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
23e70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
23e80 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
23e90 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
23ea0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
23eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
23ec0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
23ed0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
23ee0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
23ef0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
23f00 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
23f10 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
23f20 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
23f30 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
23f40 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
23f50 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
23f60 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
23f70 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
23f80 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
23f90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
23fa0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
23fb0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
23fc0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
23fd0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
23fe0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
23ff0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
24000 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  .*/.SQLITE_API S
24010 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
24020 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
24030 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
24040 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
24050 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
24060 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
24070 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
24080 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
24090 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
240a0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
240b0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
240c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
240d0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
240e0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
240f0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
24100 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a  e Event Codes.**
24110 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
24120 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68  E_TRACE.**.** Th
24130 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64  ese constants id
24140 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f  entify classes o
24150 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61  f events that ca
24160 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a  n be monitored.*
24170 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  * using the [sql
24180 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
24190 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20   tracing logic. 
241a0 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a   The M argument.
241b0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
241c0 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
241d0 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f  ] is an OR-ed co
241e0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65  mbination of one
241f0 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74   or more of.** t
24200 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
24210 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69  stants.  ^The fi
24220 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
24230 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
24240 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20  ck.** is one of 
24250 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
24260 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e  nstants..**.** N
24270 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74  ew tracing const
24280 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65  ants may be adde
24290 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
242a0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  ases..**.** ^A t
242b0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61  race callback ha
242c0 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  s four arguments
242d0 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  : xCallback(T,C,
242e0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
242f0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
24300 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74  of the integer t
24310 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e  ype codes above.
24320 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
24330 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
24340 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
24350 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61  nter passed in a
24360 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
24370 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
24380 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
24390 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
243a0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
243b0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
243c0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
243d0 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a   T..**.** <dl>.*
243e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
243f0 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49  _STMT]] <dt>SQLI
24400 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64  TE_TRACE_STMT</d
24410 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
24420 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
24430 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24440 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61  ked when a prepa
24450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
24460 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75   first begins ru
24470 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62  nning and possib
24480 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65  ly at other time
24490 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  s during the.** 
244a0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
244b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
244c0 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20  ent, such as at 
244d0 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63  the start of eac
244e0 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62  h.** trigger sub
244f0 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20  program. ^The P 
24500 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24510 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
24520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24530 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67  ent]. ^The X arg
24540 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
24550 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  er to a string w
24560 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75  hich.** is the u
24570 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65  nexpanded SQL te
24580 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
24590 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
245a0 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a  an SQL comment .
245b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
245c0 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e  s the invocation
245d0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
245e0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ^The callback ca
245f0 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65  n compute.** the
24600 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20   same text that 
24610 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20  would have been 
24620 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
24630 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
24640 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  trace()].** inte
24650 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74  rface by using t
24660 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68  he X argument wh
24670 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68  en X begins with
24680 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69   "--" and invoki
24690 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
246a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20  xpanded_sql(P)] 
246b0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
246c0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
246d0 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51  PROFILE]] <dt>SQ
246e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
246f0 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  LE</dt>.** <dd>^
24700 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24710 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
24720 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78   provides approx
24730 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65  imately the same
24740 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
24750 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  as is provided b
24760 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  y the [sqlite3_p
24770 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61  rofile()] callba
24780 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  ck..** ^The P ar
24790 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
247a0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
247b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
247c0 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
247d0 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
247e0 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
247f0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73   which is the es
24800 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68  timated of.** th
24810 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
24820 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20  second that the 
24830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24840 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
24850 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54  ** ^The SQLITE_T
24860 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
24870 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24880 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   when the statem
24890 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
248a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
248b0 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c  CE_ROW]] <dt>SQL
248c0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64  ITE_TRACE_ROW</d
248d0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
248e0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63  LITE_TRACE_ROW c
248f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24900 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72  ed whenever a pr
24910 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
24920 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20  ent generates a 
24930 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65  single row of re
24940 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20  sult.  .** ^The 
24950 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24960 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24980 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
24990 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
249a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  sed..**.** [[SQL
249b0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d  ITE_TRACE_CLOSE]
249c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
249d0 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  CE_CLOSE</dt>.**
249e0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
249f0 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c  TRACE_CLOSE call
24a00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
24a10 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a  when a database.
24a20 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  ** connection cl
24a30 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  oses..** ^The P 
24a40 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24a50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
24a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24a70 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  n] object.** and
24a80 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
24a90 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f  is unused..** </
24aa0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
24ab0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
24ac0 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
24ad0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
24ae0 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32  _PROFILE    0x02
24af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24b00 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20  TRACE_ROW       
24b10 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51   0x04.#define SQ
24b20 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
24b30 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a        0x08../*.*
24b40 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
24b50 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45  Trace Hook.** ME
24b60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
24b70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24b80 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
24b90 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  P) interface reg
24ba0 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63  isters a trace c
24bb0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
24bc0 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64  ion X against [d
24bd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24be0 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f  on] D, using pro
24bf0 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20  perty mask M.** 
24c00 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  and context poin
24c10 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20  ter P.  ^If the 
24c20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  X callback is.**
24c30 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20   NULL or if the 
24c40 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20  M mask is zero, 
24c50 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20  then tracing is 
24c60 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a  disabled.  The.*
24c70 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  * M argument sho
24c80 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69  uld be the bitwi
24c90 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  se OR-ed combina
24ca0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20  tion of.** zero 
24cb0 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f  or more [SQLITE_
24cc0 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73  TRACE] constants
24cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61  ..**.** ^Each ca
24ce0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c  ll to either sql
24cf0 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
24d00 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
24d10 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a  () overrides .**
24d20 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70   (cancels) any p
24d30 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
24d40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
24d50 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24d60 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  2()..**.** ^The 
24d70 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  X callback is in
24d80 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
24d90 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73  ny of the events
24da0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a   identified by .
24db0 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e  ** mask M occur.
24dc0 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72    ^The integer r
24dd0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
24de0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
24df0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67   currently.** ig
24e00 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68  nored, though th
24e10 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e  is may change in
24e20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
24e30 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  .  Callback.** i
24e40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
24e50 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72  hould return zer
24e60 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75  o to ensure futu
24e70 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  re compatibility
24e80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
24e90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24ea0 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61  oked with four a
24eb0 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61  rguments: callba
24ec0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
24ed0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
24ee0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53  is one of the [S
24ef0 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20  QLITE_TRACE].** 
24f00 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64  constants to ind
24f10 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61  icate why the ca
24f20 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b  llback was invok
24f30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ed..** ^The C ar
24f40 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
24f50 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
24f60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20  pointer..** The 
24f70 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
24f80 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
24f90 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
24fa0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
24fb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61   The sqlite3_tra
24fc0 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  ce_v2() interfac
24fd0 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  e is intended to
24fe0 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67   replace the leg
24ff0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
25000 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  s [sqlite3_trace
25010 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25020 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74  _profile()], bot
25030 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72  h of which.** ar
25040 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f  e deprecated..*/
25050 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
25060 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25070 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
25080 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a  unsigned uMask,.
25090 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b    int(*xCallback
250a0 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a  )(unsigned,void*
250b0 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20  ,void*,void*),. 
250c0 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a   void *pCtx.);..
250d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
250e0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
250f0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
25100 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
25110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
25120 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
25130 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
25140 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
25150 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
25160 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
25170 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
25180 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
25190 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
251a0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
251b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
251c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
251d0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
251e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
251f0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
25200 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
25210 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
25220 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
25230 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
25240 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
25250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
25260 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
25270 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
25280 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
25290 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
252a0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
252b0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
252c0 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
252d0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
252e0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
252f0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
25300 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
25310 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
25320 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
25330 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
25340 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
25350 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
25360 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
25370 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
25380 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
25390 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
253a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
253b0 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
253c0 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
253d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
253e0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
253f0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
25400 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
25410 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
25420 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
25430 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
25440 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
25450 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25460 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
25470 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
25480 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
25490 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
254a0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
254b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
254c0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
254d0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
254e0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
254f0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
25500 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
25510 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25520 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
25530 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
25540 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
25550 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
25560 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
25570 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
25580 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
25590 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
255a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
255b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
255c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
255d0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
255e0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
255f0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
25600 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
25610 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
25620 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
25630 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
25640 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
25650 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
25660 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
25670 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c  graph..**.*/.SQL
25680 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
25690 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
256a0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
256b0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
256c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
256d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
256e0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
256f0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
25700 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
25710 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
25720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
25730 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
25740 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
25750 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
25760 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
25770 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
25780 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
25790 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
257a0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
257b0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
257c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
257d0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
257e0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
257f0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
25800 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
25810 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
25820 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
25830 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
25840 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
25850 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
25860 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
25870 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
25880 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
25890 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
258a0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
258b0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
258c0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
258d0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
258e0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
258f0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
25900 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
25910 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
25920 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
25930 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25940 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
25950 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
25960 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
25970 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
25980 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
25990 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
259a0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
259b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
259c0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
259d0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
259e0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
259f0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
25a00 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
25a10 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
25a20 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
25a30 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
25a40 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
25a50 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
25a60 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
25a70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
25a80 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
25a90 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
25aa0 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
25ab0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
25ac0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
25ad0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
25ae0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
25af0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
25b00 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
25b10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
25b20 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
25b30 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
25b40 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
25b50 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
25b60 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
25b70 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
25b80 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
25b90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25ba0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25bb0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
25bc0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
25bd0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
25be0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
25bf0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
25c00 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
25c10 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
25c20 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
25c30 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
25c40 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
25c50 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
25c60 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
25c70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
25c80 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
25c90 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
25ca0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
25cb0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
25cc0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
25cd0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
25ce0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
25cf0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
25d00 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
25d10 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
25d20 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
25d30 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
25d40 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
25d50 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
25d60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
25d70 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
25d80 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
25d90 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
25da0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
25db0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
25dc0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
25dd0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
25de0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25df0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
25e00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
25e10 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25e20 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
25e30 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
25e40 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
25e50 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
25e60 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
25e70 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
25e80 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25e90 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25ea0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25eb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25ec0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
25ed0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
25ee0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
25ef0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
25f00 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
25f10 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
25f20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25f30 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
25f40 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
25f50 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
25f60 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
25f70 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
25f80 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
25f90 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
25fa0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25fb0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
25fc0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
25fd0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25fe0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25ff0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
26000 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
26010 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
26020 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
26030 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
26040 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
26050 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
26060 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
26070 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
26080 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
26090 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
260a0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
260b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
260c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
260d0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
260e0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
260f0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
26100 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
26110 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
26120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
26130 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
26140 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
26150 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
26160 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26170 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
26180 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
26190 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
261a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
261b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
261c0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
261d0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
261e0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
261f0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
26200 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
26210 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
26220 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
26230 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
26240 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
26250 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
26260 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
26270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26280 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
26290 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
262a0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
262b0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
262c0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
262d0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
262e0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
262f0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
26300 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
26310 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
26320 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
26330 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
26340 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
26350 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
26360 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
26370 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
26380 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26390 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
263a0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
263b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
263c0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
263d0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
263e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
263f0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
26400 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
26410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
26420 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
26430 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
26440 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
26450 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
26460 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
26470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
26480 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26490 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
264a0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
264b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
264c0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
264d0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
264e0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
264f0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
26500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
26510 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
26520 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
26530 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
26540 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
26550 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
26560 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
26570 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
26580 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
26590 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
265a0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
265b0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
265c0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
265d0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
265e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
265f0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
26600 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
26610 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
26620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26630 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
26640 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
26650 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
26660 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
26670 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
26680 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
26690 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
266a0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
266b0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
266c0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
266d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
266e0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
266f0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
26700 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
26710 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
26720 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
26730 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
26740 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
26750 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
26760 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
26770 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
26780 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
26790 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
267a0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
267b0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
267c0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
267d0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
267e0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
267f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
26800 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
26810 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26820 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
26830 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
26840 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
26850 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
26860 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
26870 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
26880 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
26890 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
268a0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
268b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
268c0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
268d0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
268e0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
268f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
26900 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
26910 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
26920 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
26930 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
26940 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
26950 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68  ** set in the th
26960 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
26970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26980 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
26990 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
269a0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
269b0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
269c0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
269d0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
269e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
269f0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
26a00 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
26a10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
26a20 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  on..** URI filen
26a30 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
26a40 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
26a50 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
26a60 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
26a70 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
26a80 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
26a90 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
26aa0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
26ab0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
26ac0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
26ad0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
26ae0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
26af0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
26b00 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
26b10 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
26b20 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
26b30 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
26b40 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
26b50 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
26b60 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
26b70 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
26b80 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
26b90 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
26ba0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
26bb0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
26bc0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
26bd0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26be0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
26bf0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
26c00 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
26c10 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
26c20 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
26c30 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
26c40 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
26c50 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
26c60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26c70 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
26c80 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
26c90 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
26ca0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
26cb0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
26cc0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
26cd0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26ce0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
26cf0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
26d00 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
26d10 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
26d20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
26d30 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
26d40 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
26d50 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
26d60 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
26d70 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26d80 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
26d90 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
26da0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
26db0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
26dc0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
26dd0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
26de0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
26df0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
26e00 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
26e10 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
26e20 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
26e30 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
26e40 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
26e50 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
26e60 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
26e70 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
26e80 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
26e90 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
26ea0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
26eb0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
26ec0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
26ed0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
26ee0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
26ef0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
26f00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
26f10 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
26f20 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
26f30 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
26f40 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
26f50 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
26f60 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
26f70 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
26f80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
26f90 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
26fa0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
26fb0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
26fc0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
26fd0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
26fe0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
26ff0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
27000 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
27010 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
27020 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
27030 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
27040 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
27050 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
27060 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27070 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
27080 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
27090 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
270a0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
270b0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
270c0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
270d0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
270e0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
270f0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
27100 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27110 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
27120 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
27130 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
27140 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27150 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27160 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
27170 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
27180 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
27190 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
271a0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
271b0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
271c0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
271d0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
271e0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
271f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27200 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
27210 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
27220 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
27230 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
27240 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
27250 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
27260 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
27270 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27280 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
27290 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
272a0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
272b0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
272c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
272d0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
272e0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
272f0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
27300 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
27310 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
27320 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
27330 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
27340 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
27350 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
27360 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
27370 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
27380 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
27390 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
273a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
273b0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
273c0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
273d0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
273e0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
273f0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
27400 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
27410 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
27420 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
27430 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
27440 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
27450 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
27460 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
27470 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
27480 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
27490 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
274a0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
274b0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
274c0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
274d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
274e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
274f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
27500 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
27510 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
27520 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
27530 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
27540 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
27550 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
27560 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
27570 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
27580 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
27590 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
275a0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
275b0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
275c0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
275d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
275e0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
275f0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
27600 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
27610 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
27620 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
27630 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
27640 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
27650 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
27660 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
27670 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
27680 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
27690 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
276a0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
276b0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
276c0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
276d0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
276e0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
276f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
27700 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
27710 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
27720 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
27730 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
27740 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
27750 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
27760 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
27770 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
27780 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
27790 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
277a0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
277b0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
277c0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
277d0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
277e0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
277f0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
27800 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
27810 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
27820 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
27830 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
27840 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
27850 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
27860 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
27870 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
27880 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
27890 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
278a0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
278b0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
278c0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
278d0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
278e0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
278f0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
27900 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
27910 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
27920 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
27930 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
27940 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
27950 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
27960 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
27970 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
27980 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
27990 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
279a0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
279b0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
279c0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
279d0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
279e0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
279f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
27a00 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
27a10 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
27a20 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
27a30 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
27a40 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
27a50 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
27a60 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
27a70 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
27a80 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
27a90 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
27aa0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
27ab0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
27ac0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27ad0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
27ae0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
27af0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
27b00 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
27b10 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
27b20 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
27b30 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
27b40 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
27b50 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
27b60 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
27b70 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
27b80 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
27b90 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
27ba0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
27bb0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
27bc0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
27bd0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
27be0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
27bf0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
27c00 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
27c10 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
27c20 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
27c30 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
27c40 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
27c50 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
27c60 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
27c70 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
27c80 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
27c90 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
27ca0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
27cb0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
27cc0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
27cd0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
27ce0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
27cf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27d00 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
27d10 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
27d20 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
27d30 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
27d40 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
27d50 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
27d60 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
27d70 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
27d80 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
27d90 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
27da0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
27db0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27dc0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
27dd0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
27de0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
27df0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
27e00 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
27e10 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
27e20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
27e30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27e40 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
27e50 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
27e60 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
27e70 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
27e80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27e90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27ea0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
27eb0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
27ec0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
27ed0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
27ee0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
27ef0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
27f00 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
27f10 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
27f20 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
27f30 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
27f40 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
27f50 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
27f60 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
27f70 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
27f80 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
27f90 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
27fa0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
27fb0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
27fc0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27fd0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
27fe0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
27ff0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
28000 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
28010 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
28020 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
28030 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
28040 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
28050 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
28060 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
28070 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
28080 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
28090 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
280a0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
280b0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
280c0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
280d0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
280e0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
280f0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
28100 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
28110 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
28120 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
28130 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
28140 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
28150 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
28160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
28170 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
28180 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
28190 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
281a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
281b0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
281c0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
281d0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
281e0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
281f0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
28200 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
28210 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
28220 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
28230 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
28240 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
28250 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
28260 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
28270 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
28280 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
28290 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
282a0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
282b0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
282c0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
282d0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
282e0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
282f0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
28300 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
28310 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
28320 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
28330 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
28340 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
28350 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
28360 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
28370 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
28380 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
28390 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
283a0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
283b0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
283c0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
283d0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
283e0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
283f0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
28400 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
28410 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
28420 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
28430 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
28440 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
28450 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
28460 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
28470 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
28480 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
28490 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
284a0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
284b0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
284c0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
284d0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
284e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
284f0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
28500 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
28510 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
28520 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
28530 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
28540 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
28550 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
28560 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
28570 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
28580 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
28590 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
285a0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
285b0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
285c0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
285d0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
285e0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
285f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
28600 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
28610 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
28620 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
28630 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
28640 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
28650 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
28660 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
28670 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
28680 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
28690 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
286a0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
286b0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
286c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
286d0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
286e0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
286f0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
28700 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
28710 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
28720 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
28730 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28740 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
28750 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
28760 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28770 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
28780 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
28790 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
287a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
287b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
287c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
287d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
287e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
287f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28800 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
28810 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
28820 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
28830 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
28840 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
28850 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
28860 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
28870 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
28880 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
28890 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
288a0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
288b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
288c0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
288d0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
288e0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
288f0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
28900 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
28910 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
28920 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
28930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
28940 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
28950 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
28960 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
28970 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
28980 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
28990 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
289a0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
289b0 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
289c0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
289d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
289e0 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
289f0 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
28a00 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
28a10 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
28a20 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
28a30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
28a40 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
28a50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28a60 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
28a70 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
28a80 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
28a90 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
28aa0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
28ab0 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
28ac0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
28ad0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
28ae0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
28af0 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
28b00 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
28b10 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
28b20 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
28b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
28b40 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
28b50 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
28b60 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
28b70 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
28b80 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
28b90 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
28ba0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
28bb0 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
28bc0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
28bd0 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
28be0 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
28bf0 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
28c00 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
28c10 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
28c20 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
28c30 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
28c40 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
28c50 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
28c60 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
28c70 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
28c80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
28c90 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
28ca0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
28cb0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28cc0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
28cd0 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
28ce0 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
28cf0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
28d00 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
28d10 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
28d20 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
28d30 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
28d40 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28d50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
28d60 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
28d70 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
28d80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28d90 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
28da0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
28db0 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
28dc0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
28dd0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
28de0 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
28df0 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
28e00 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28e10 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
28e20 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
28e30 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
28e40 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
28e50 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
28e60 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
28e70 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
28e80 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
28e90 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
28ea0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
28eb0 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
28ec0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
28ed0 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
28ee0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
28ef0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
28f00 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
28f10 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
28f20 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28f30 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
28f40 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
28f50 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
28f60 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
28f70 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
28f80 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
28f90 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
28fa0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
28fb0 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
28fc0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
28fd0 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
28fe0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
28ff0 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
29000 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
29010 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
29020 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
29030 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
29040 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
29050 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
29060 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
29070 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
29080 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
29090 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
290a0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
290b0 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
290c0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
290d0 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
290e0 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
290f0 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
29100 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
29110 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
29120 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
29130 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
29140 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
29150 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
29160 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
29170 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
29180 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29190 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
291a0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
291b0 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
291c0 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
291d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
291e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
291f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
29200 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
29210 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
29220 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
29230 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
29240 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
29250 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
29260 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
29270 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
29280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
29290 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
292a0 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
292b0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
292c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
292d0 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
292e0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
292f0 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
29300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29310 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
29320 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
29330 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
29340 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
29350 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
29360 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
29370 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
29380 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
29390 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
293a0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
293b0 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
293c0 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
293d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
293e0 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
293f0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
29400 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
29410 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
29420 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
29430 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
29440 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
29450 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
29460 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
29470 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
29480 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
29490 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
294a0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
294b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
294c0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
294d0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
294e0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
294f0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
29500 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
29510 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
29520 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29530 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
29540 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29550 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29560 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29570 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29580 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
29590 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
295a0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
295b0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
295c0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
295d0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
295e0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
295f0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
29600 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
29610 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
29620 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
29630 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
29640 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
29650 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
29660 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
29670 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
29680 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
29690 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
296a0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
296b0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
296c0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
296d0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
296e0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
296f0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
29700 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
29710 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
29720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
29730 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
29740 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
29750 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
29760 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
29770 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
29780 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
29790 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
297a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
297b0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
297c0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
297d0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
297e0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
297f0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
29800 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
29810 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
29820 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
29830 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
29840 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
29850 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
29860 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
29870 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
29880 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
29890 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
298a0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
298b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
298c0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
298d0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
298e0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
298f0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
29900 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
29910 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
29920 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
29930 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
29940 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
29950 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
29960 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
29970 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
29980 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
29990 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
299a0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
299b0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
299c0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
299d0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
299e0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
299f0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
29a00 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
29a10 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
29a20 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
29a30 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
29a40 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
29a50 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
29a60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29a70 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
29a80 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
29a90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29aa0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
29ab0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
29ac0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29ad0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
29ae0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
29af0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29b00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
29b10 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
29b20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29b30 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29b40 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
29b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29b60 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29b70 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
29b80 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
29b90 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
29ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
29bb0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
29bc0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
29bd0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
29be0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
29bf0 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
29c00 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
29c10 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
29c20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
29c30 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
29c40 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
29c50 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
29c60 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
29c70 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
29c80 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
29c90 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
29ca0 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
29cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29cc0 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
29cd0 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
29ce0 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
29cf0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29d00 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
29d10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29d20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
29d30 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
29d40 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
29d50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29d60 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
29d70 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
29d80 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
29d90 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
29da0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29db0 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
29dc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29dd0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
29de0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
29df0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
29e00 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
29e10 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
29e20 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
29e30 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
29e40 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29e50 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
29e60 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
29e70 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
29e80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e90 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
29ea0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
29eb0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
29ec0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
29ed0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
29ee0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
29ef0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
29f00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
29f10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
29f20 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
29f30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
29f40 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
29f50 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
29f60 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
29f70 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
29f80 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
29f90 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
29fa0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
29fb0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
29fc0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
29fd0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
29fe0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
29ff0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
2a000 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2a010 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
2a020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a030 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
2a040 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
2a050 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
2a060 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2a070 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
2a080 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
2a090 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
2a0a0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
2a0b0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
2a0c0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
2a0d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
2a0e0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
2a0f0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
2a100 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
2a110 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
2a120 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
2a130 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
2a140 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
2a150 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
2a160 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
2a170 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
2a180 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
2a190 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
2a1a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
2a1b0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
2a1c0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
2a1d0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
2a1e0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
2a1f0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
2a200 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
2a210 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
2a220 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
2a230 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
2a240 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
2a250 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
2a260 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
2a270 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2a280 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
2a290 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
2a2a0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
2a2b0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
2a2c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2a2d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
2a2e0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
2a2f0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
2a300 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
2a310 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
2a320 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
2a330 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
2a340 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
2a350 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
2a360 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
2a370 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
2a380 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
2a390 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
2a3a0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
2a3b0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
2a3c0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
2a3d0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
2a3e0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
2a3f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2a400 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
2a410 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
2a420 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
2a430 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
2a440 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
2a450 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
2a460 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
2a470 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
2a480 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
2a490 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
2a4a0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
2a4b0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
2a4c0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
2a4d0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
2a4e0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
2a4f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
2a500 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
2a510 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
2a520 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
2a530 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
2a540 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
2a550 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
2a560 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
2a570 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
2a580 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
2a590 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2a5a0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
2a5b0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
2a5c0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
2a5d0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
2a5e0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
2a5f0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
2a600 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
2a610 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
2a620 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
2a630 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
2a640 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
2a650 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
2a660 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
2a670 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
2a680 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
2a690 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
2a6a0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
2a6b0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
2a6c0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
2a6d0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
2a6e0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
2a6f0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
2a700 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2a710 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2a720 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2a730 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
2a740 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
2a750 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
2a760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a770 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
2a780 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
2a790 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
2a7a0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
2a7b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
2a7c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2a7d0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2a7e0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
2a7f0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
2a800 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
2a810 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
2a820 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2a830 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
2a840 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
2a850 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
2a860 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
2a870 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
2a880 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2a890 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
2a8a0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
2a8b0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
2a8c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2a8d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a8e0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2a8f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
2a900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a910 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
2a920 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
2a930 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
2a940 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
2a950 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a960 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a970 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a980 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a990 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a9a0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2a9b0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
2a9c0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
2a9d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a9f0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
2aa00 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
2aa10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2aa20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2aa30 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
2aa40 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
2aa50 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
2aa60 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2aa70 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
2aa80 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
2aa90 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
2aaa0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
2aab0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
2aac0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
2aad0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2aae0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2aaf0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2ab00 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2ab10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ab20 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
2ab30 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
2ab40 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
2ab50 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2ab60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ab70 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
2ab80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2ab90 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2aba0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
2abb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2abc0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
2abd0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
2abe0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
2abf0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2ac00 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2ac10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2ac20 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
2ac30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2ac40 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2ac50 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
2ac60 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
2ac70 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
2ac80 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
2ac90 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2aca0 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72    If [sqlite3_pr
2acb0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
2acc0 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  * the equivalent
2acd0 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61   tries to alloca
2ace0 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72  te space for mor
2acf0 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79  e than this many
2ad00 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61   opcodes.** in a
2ad10 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64   single prepared
2ad20 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53   statement, an S
2ad30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f  QLITE_NOMEM erro
2ad40 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
2ad50 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2ad60 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2ad70 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
2ad80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2ad90 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
2ada0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2adb0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
2adc0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
2add0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2ade0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2adf0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
2ae00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
2ae10 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
2ae20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2ae30 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
2ae40 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
2ae50 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
2ae60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2ae70 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2ae80 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
2ae90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2aea0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2aeb0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2aec0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2aed0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
2aee0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
2aef0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
2af00 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
2af10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2af20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2af30 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
2af40 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2af50 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2af60 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
2af70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
2af80 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
2af90 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
2afa0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2afb0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
2afc0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2afd0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2afe0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2aff0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
2b000 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2b010 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
2b020 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
2b030 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2b040 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2b050 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
2b060 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b070 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2b080 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
2b090 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b0a0 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
2b0b0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
2b0c0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
2b0d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b0e0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
2b0f0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
2b100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b110 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
2b120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b130 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
2b140 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2b150 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2b160 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2b170 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
2b180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b190 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2b1a0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2b1b0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
2b1c0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2b1d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2b1e0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
2b1f0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2b200 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2b210 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
2b220 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
2b230 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2b240 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
2b250 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
2b260 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
2b270 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
2b280 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
2b290 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2b2a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2b2b0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
2b2c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2b2d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
2b2e0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
2b2f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2b300 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
2b310 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
2b320 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2b330 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2b340 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
2b350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
2b360 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a  repare Flags.**.
2b370 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2b380 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2b390 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e  s flags that can
2b3a0 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a   be passed into.
2b3b0 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70  ** "prepFlags" p
2b3c0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2b3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b3e0 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  _v3()] and.** [s
2b3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b400 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v3()] interface
2b410 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61  s..**.** New fla
2b420 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  gs may be added 
2b430 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2b440 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
2b450 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2b460 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2b470 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e  SISTENT]] ^(<dt>
2b480 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b490 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a  ERSISTENT</dt>.*
2b4a0 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2b4b0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2b4c0 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69  ENT flag is a hi
2b4d0 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20  nt to the query 
2b4e0 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20  planner.** that 
2b4f0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2b500 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72  tement will be r
2b510 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f  etained for a lo
2b520 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70  ng time and.** p
2b530 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d  robably reused m
2b540 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69  any times.)^ ^Wi
2b550 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c  thout this flag,
2b560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b570 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  e_v3()].** and [
2b580 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b590 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74  6_v3()] assume t
2b5a0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2b5b0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2b5c0 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74  .** be used just
2b5d0 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74   once or at most
2b5e0 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64   a few times and
2b5f0 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20   then destroyed 
2b600 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2b610 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65  3_finalize()] re
2b620 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54  latively soon. T
2b630 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
2b640 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a  mentation acts.*
2b650 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62  * on this hint b
2b660 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75  y avoiding the u
2b670 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65  se of [lookaside
2b680 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e   memory] so as n
2b690 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65  ot to.** deplete
2b6a0 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f   the limited sto
2b6b0 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  re of lookaside 
2b6c0 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76  memory. Future v
2b6d0 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51  ersions of.** SQ
2b6e0 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20  Lite may act on 
2b6f0 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72  this hint differ
2b700 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ently..** </dl>.
2b710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b720 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2b730 54 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  TENT            
2b740 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x01../*.** CA
2b750 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
2b760 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
2b770 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
2b780 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
2b790 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  ompiler}.** METH
2b7a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43  OD: sqlite3.** C
2b7b0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
2b7c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
2b7d0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
2b7e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d   statement, it m
2b7f0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
2b800 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
2b810 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
2b820 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
2b830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20  hese routines.  
2b840 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  Or, in other wor
2b850 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ds, these routin
2b860 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72  es.** are constr
2b870 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b  uctors for the [
2b880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b890 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  nt] object..**.*
2b8a0 2a 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20  * The preferred 
2b8b0 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69  routine to use i
2b8c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2b8d0 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a  re_v2()].  The.*
2b8e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b8f0 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  re()] interface 
2b900 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68  is legacy and sh
2b910 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2b920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b930 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61  pare_v3()] has a
2b940 6e 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61  n extra "prepFla
2b950 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20  gs" option that 
2b960 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73  is used.** for s
2b970 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e  pecial purposes.
2b980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f  .**.** The use o
2b990 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65  f the UTF-8 inte
2b9a0 72 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72  rfaces is prefer
2b9b0 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63  red, as SQLite c
2b9c0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73  urrently.** does
2b9d0 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69   all parsing usi
2b9e0 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55  ng UTF-8.  The U
2b9f0 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73  TF-16 interfaces
2ba00 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
2ba10 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   as a convenienc
2ba20 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69  e.  The UTF-16 i
2ba30 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62  nterfaces work b
2ba40 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65  y converting the
2ba50 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69  .** input text i
2ba60 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20  nto UTF-8, then 
2ba70 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72  invoking the cor
2ba80 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38  responding UTF-8
2ba90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2baa0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
2bab0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
2bac0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bad0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
2bae0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
2baf0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2bb00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2bb10 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2bb20 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
2bb30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2bb40 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
2bb50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2bb60 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
2bb70 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
2bb80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2bb90 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
2bba0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2bbb0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
2bbc0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
2bbd0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
2bbe0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
2bbf0 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33  epare(), sqlite3
2bc00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a  _prepare_v2(),.*
2bc10 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2bc20 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e  epare_v3().** in
2bc30 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
2bc40 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
2bc50 70 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c  prepare16(), sql
2bc60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bc70 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2bc80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2bc90 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  () use UTF-16..*
2bca0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
2bcb0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e  te argument is n
2bcc0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53  egative, then zS
2bcd0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
2bce0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
2bcf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
2bd00 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69  If nByte is posi
2bd10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
2bd20 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2bd30 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  f bytes read fro
2bd40 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79  m zSql.  ^If nBy
2bd50 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  te is zero, then
2bd60 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20   no prepared.** 
2bd70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e  statement is gen
2bd80 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68  erated..** If th
2bd90 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74  e caller knows t
2bda0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
2bdb0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
2bdc0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a  erminated, then.
2bdd0 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  ** there is a sm
2bde0 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  all performance 
2bdf0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73  advantage to pas
2be00 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
2be10 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
2be20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2be30 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
2be40 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
2be50 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
2be60 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
2be70 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  r..**.** ^If pzT
2be80 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
2be90 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
2bea0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2beb0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
2bec0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
2bed0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
2bee0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2bef0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
2bf00 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
2bf10 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
2bf20 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
2bf30 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
2bf40 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
2bf50 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
2bf60 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
2bf70 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
2bf80 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
2bf90 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
2bfa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2bfb0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
2bfc0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
2bfd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
2bfe0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
2bff0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
2c000 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
2c010 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
2c020 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
2c030 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
2c040 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
2c050 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
2c060 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
2c070 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
2c080 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
2c090 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
2c0a0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
2c0b0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2c0c0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
2c0d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2c0e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c0f0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
2c100 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2c110 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
2c120 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
2c130 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
2c140 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
2c150 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
2c160 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c170 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
2c180 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
2c190 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2c1a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
2c1b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c1c0 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v2(), sqlite3_p
2c1d0 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c  repare_v3(), sql
2c1e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c1f0 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2c200 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2c210 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2c220 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  e recommended fo
2c230 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
2c240 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72  ms..** The older
2c250 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c   interfaces (sql
2c260 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
2c270 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2c280 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72  re16()).** are r
2c290 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
2c2a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2c2b0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
2c2c0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
2c2d0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
2c2e0 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  X" interfaces, t
2c2f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2c300 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
2c310 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
2c320 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2c330 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
2c340 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2c350 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
2c360 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
2c370 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2c380 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
2c390 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
2c3a0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
2c3b0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
2c3c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2c3d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2c3e0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
2c3f0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
2c400 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
2c410 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
2c420 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
2c430 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2c440 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2c450 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
2c460 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2c470 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
2c480 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
2c490 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
2c4a0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
2c4b0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
2c4c0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
2c4d0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
2c4e0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
2c4f0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
2c500 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2c510 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
2c520 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
2c530 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
2c540 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
2c550 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
2c560 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
2c570 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2c580 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
2c590 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
2c5a0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
2c5b0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
2c5c0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
2c5d0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
2c5e0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
2c5f0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
2c600 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
2c610 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
2c620 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
2c630 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
2c640 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2c650 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
2c660 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
2c670 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
2c680 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
2c690 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
2c6a0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
2c6b0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
2c6c0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
2c6d0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
2c6e0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
2c6f0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
2c700 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
2c710 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
2c720 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2c730 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
2c740 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
2c750 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
2c760 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
2c770 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
2c780 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
2c790 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
2c7a0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2c7b0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
2c7c0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
2c7d0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
2c7e0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
2c7f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2c800 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
2c810 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
2c820 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2c830 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
2c840 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
2c850 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
2c860 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
2c870 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
2c880 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
2c890 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
2c8a0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
2c8b0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
2c8c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
2c8d0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
2c8e0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
2c8f0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
2c900 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
2c910 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
2c920 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
2c930 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
2c940 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
2c950 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
2c960 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
2c970 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
2c980 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33  *.** <p>^sqlite3
2c990 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69  _prepare_v3() di
2c9a0 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74  ffers from sqlit
2c9b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2c9c0 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a  only in having.*
2c9d0 2a 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70  * the extra prep
2c9e0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c  Flags parameter,
2c9f0 20 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20   which is a bit 
2ca00 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67  array consisting
2ca10 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d   of zero or.** m
2ca20 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
2ca30 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2ca40 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45  STENT|SQLITE_PRE
2ca50 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20  PARE_*] flags.  
2ca60 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2ca70 70 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74  prepare_v2() int
2ca80 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61  erface works exa
2ca90 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
2caa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2cab0 61 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20  are_v3() with a 
2cac0 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70  zero prepFlags p
2cad0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f  arameter..** </o
2cae0 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
2caf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2cb00 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
2cb10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2cb20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2cb30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2cb40 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2cb50 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2cb60 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2cb70 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2cb80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2cb90 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2cba0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2cbb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2cbc0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2cbd0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2cbe0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2cbf0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2cc00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2cc10 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2cc20 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2cc30 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2cc40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2cc50 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2cc60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2cc70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2cc80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2cc90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2cca0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ccb0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2ccc0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2ccd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cce0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2ccf0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2cd00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2cd10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2cd20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2cd30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cd40 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2cd50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2cd60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2cd70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2cd80 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2cd90 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2cda0 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65  are_v3(.  sqlite
2cdb0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2cdc0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2cdd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cde0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2cdf0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ce00 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2ce10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ce20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ce30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ce40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ce50 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2ce60 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2ce70 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2ce80 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2ce90 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2cea0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ceb0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2cec0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ced0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2cee0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2cef0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2cf00 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2cf10 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2cf20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2cf30 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2cf40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2cf50 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2cf60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cf70 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2cf80 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2cf90 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2cfa0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2cfb0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2cfc0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2cfd0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2cfe0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2cff0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2d000 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2d010 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2d020 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2d030 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2d040 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2d050 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2d060 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2d070 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d080 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2d090 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d0a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d0b0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d0c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2d0d0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d0e0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2d0f0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2d100 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2d110 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2d120 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2d130 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2d140 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2d150 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2d160 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2d170 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d180 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2d190 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2d1a0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2d1b0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2d1c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2d1d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2d1e0 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2d1f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2d200 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2d210 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2d220 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2d230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2d240 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2d250 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2d260 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2d270 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2d280 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2d290 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2d2a0 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2d2b0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2d2c0 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2d2d0 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2d2e0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2d2f0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2d300 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2d310 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2d320 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2d330 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2d340 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2d350 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2d360 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2d370 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2d380 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d390 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2d3a0 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  e sqlite3_sql(P)
2d3b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d3c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d3d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54  a copy of the UT
2d3e0 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  F-8.** SQL text 
2d3f0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b  used to create [
2d400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d410 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a  nt] P if P was.*
2d420 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  * created by [sq
2d430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d440 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
2d450 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20  epare_v3()],.** 
2d460 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d470 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71  16_v2()], or [sq
2d480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d490 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v3()]..** ^The s
2d4a0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d4b0 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2d4c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d4d0 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2d4e0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2d4f0 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2d500 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2d510 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2d520 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2d530 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2d540 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d550 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2d560 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2d570 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2d580 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2d590 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2d5a0 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2d5b0 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2d5c0 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2d5d0 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2d5e0 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2d5f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2d600 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2d610 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2d620 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2d630 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2d640 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d650 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2d660 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2d670 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2d680 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2d690 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2d6a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2d6b0 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2d6c0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2d6d0 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2d6e0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2d6f0 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2d700 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2d710 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2d720 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2d730 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2d740 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2d750 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2d760 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2d770 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2d780 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2d790 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2d7a0 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2d7b0 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2d7c0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2d7d0 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2d7e0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2d7f0 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2d800 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2d810 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2d820 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2d830 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2d840 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2d850 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2d860 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2d870 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2d880 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2d890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d8a0 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2d8b0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2d8c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d8d0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d8e0 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2d8f0 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2d900 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d910 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2d920 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2d930 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2d940 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2d950 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2d960 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ree()]..*/.SQLIT
2d970 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d980 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2d990 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d9a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d9b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70  har *sqlite3_exp
2d9c0 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65  anded_sql(sqlite
2d9d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d9e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d9f0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2da00 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2da10 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2da20 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
2da30 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2da40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2da50 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2da60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2da70 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2da80 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2da90 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2daa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2dab0 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2dac0 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2dad0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2dae0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2daf0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2db00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2db10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2db20 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2db30 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2db40 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2db50 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2db60 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2db70 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2db80 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2db90 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2dba0 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2dbb0 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2dbc0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2dbd0 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2dbe0 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2dbf0 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2dc00 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2dc10 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2dc20 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2dc30 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2dc40 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2dc50 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2dc60 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2dc70 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2dc80 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2dc90 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2dca0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2dcb0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2dcc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2dcd0 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2dce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2dcf0 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2dd00 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2dd10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2dd20 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2dd30 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2dd40 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2dd50 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2dd60 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2dd70 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2dd80 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2dd90 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2dda0 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2ddb0 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2ddc0 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2ddd0 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2dde0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2ddf0 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2de00 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2de10 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2de20 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2de30 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2de40 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2de50 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2de60 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2de70 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2de80 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2de90 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2dea0 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2deb0 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2dec0 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2ded0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2dee0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2def0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2df00 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2df10 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2df20 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2df30 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2df40 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  disk..** ^The sq
2df50 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2df60 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  nly() interface 
2df70 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72  returns true for
2df80 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a   [BEGIN] since.*
2df90 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79  * [BEGIN] merely
2dfa0 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66   sets internal f
2dfb0 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42  lags, but the [B
2dfc0 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44  EGIN|BEGIN IMMED
2dfd0 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45  IATE] and.** [BE
2dfe0 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53  GIN|BEGIN EXCLUS
2dff0 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f  IVE] commands do
2e000 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62   touch the datab
2e010 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71  ase and so.** sq
2e020 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2e030 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61  nly() returns fa
2e040 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f  lse for those co
2e050 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54  mmands..*/.SQLIT
2e060 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e070 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e080 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e090 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e0a0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2e0b0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2e0c0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2e0d0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2e0e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e0f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e100 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2e110 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e120 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2e130 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2e140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e150 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2e160 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2e170 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2e180 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2e190 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2e1a0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2e1b0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2e1c0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2e1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2e1e0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2e1f0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2e200 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2e210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2e220 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2e230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2e240 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2e250 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2e260 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2e270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2e280 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2e290 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2e2a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e2b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2e2c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2e2d0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2e2e0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2e2f0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2e300 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2e310 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2e320 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2e330 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2e340 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2e350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e360 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e370 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2e380 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2e390 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2e3a0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2e3b0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2e3c0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2e3d0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2e3e0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2e3f0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2e400 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2e410 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2e420 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2e430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2e440 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2e450 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2e460 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e470 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2e480 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2e490 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2e4a0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2e4b0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2e4c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e4d0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2e4e0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2e4f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e500 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2e510 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2e520 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2e530 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2e540 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2e550 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2e560 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2e570 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2e580 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2e590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e5a0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2e5b0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2e5c0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2e5d0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2e5e0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2e5f0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2e600 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2e610 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2e620 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2e630 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2e640 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2e650 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e660 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2e670 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2e680 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2e690 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2e6a0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2e6b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2e6c0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2e6d0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2e6e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2e6f0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2e700 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2e710 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2e720 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e730 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2e740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e750 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2e760 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2e770 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2e780 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2e790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2e7a0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2e7b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2e7d0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2e7e0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2e7f0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2e800 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2e810 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2e820 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2e830 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2e840 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e850 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2e860 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2e870 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2e880 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e890 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2e8a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2e8b0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2e8c0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2e8d0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2e8e0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2e8f0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2e900 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2e910 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2e920 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2e930 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2e940 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2e950 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e960 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2e970 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e980 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2e990 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2e9a0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2e9b0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2e9c0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2e9d0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e9e0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2e9f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2ea00 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2ea10 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2ea20 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2ea30 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2ea40 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2ea50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2ea60 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2ea70 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2ea80 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2ea90 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2eaa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2eab0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2eac0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2ead0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2eae0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2eaf0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2eb00 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2eb10 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2eb20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2eb30 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2eb40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2eb50 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2eb60 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2eb70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2eb80 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2eb90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2eba0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2ebb0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2ebc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ebd0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2ebe0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2ebf0 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2ec00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ec10 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2ec20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2ec30 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2ec40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2ec50 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2ec60 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2ec70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ec80 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2ec90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2eca0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2ecb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ecc0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2ecd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2ece0 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2ecf0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2ed00 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2ed10 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2ed20 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2ed30 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2ed40 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2ed50 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2ed60 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2ed70 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2ed80 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2ed90 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2eda0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2edb0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2edc0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2edd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ede0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2edf0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2ee00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ee10 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2ee20 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2ee30 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2ee40 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2ee50 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ee60 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2ee70 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2ee80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2ee90 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2eea0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2eeb0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2eec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2eed0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2eee0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2eef0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2ef00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ef10 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2ef20 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2ef30 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2ef40 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2ef50 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2ef60 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2ef70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2ef80 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2ef90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2efa0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2efb0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2efc0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2efd0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2efe0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2eff0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2f000 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2f010 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f020 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2f030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2f040 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2f050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f060 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2f070 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2f080 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2f090 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2f0a0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2f0b0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2f0c0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2f0d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2f0e0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2f0f0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2f100 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2f110 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2f120 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2f130 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2f140 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2f150 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2f160 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2f170 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2f180 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2f190 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2f1a0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2f1b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2f1c0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2f1d0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2f1e0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2f1f0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2f200 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2f210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f220 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2f230 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2f240 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f250 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2f260 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2f270 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2f280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2f290 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2f2a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2f2b0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2f2c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2f2d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2f2e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2f2f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2f300 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2f310 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2f320 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2f330 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2f340 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2f350 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2f360 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2f370 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2f380 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2f390 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2f3a0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2f3b0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2f3c0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2f3d0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2f3e0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2f3f0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2f400 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2f410 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2f420 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2f430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f440 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2f450 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2f460 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2f470 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2f480 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2f490 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2f4a0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2f4b0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2f4c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2f4d0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2f4e0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2f4f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2f500 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2f510 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2f520 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2f530 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2f540 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2f550 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2f560 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2f570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f580 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2f590 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2f5a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f5b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2f5c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2f5d0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2f5e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2f5f0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2f600 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2f610 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2f620 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2f630 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2f640 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2f650 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2f660 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2f670 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f680 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2f690 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2f6a0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2f6b0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2f6c0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2f6d0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2f6e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2f6f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2f700 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2f710 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2f720 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f730 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f740 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2f750 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2f760 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2f770 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2f780 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2f790 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2f7a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2f7b0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2f7c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f7d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2f7e0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2f7f0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2f800 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2f810 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2f820 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2f830 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2f840 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2f850 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2f860 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f870 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2f880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f890 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2f8a0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2f8b0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2f8c0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2f8d0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2f8e0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2f8f0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2f900 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2f910 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2f920 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2f930 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2f940 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2f950 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2f960 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f970 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2f980 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2f990 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2f9a0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2f9b0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2f9c0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2f9d0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2f9e0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2f9f0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2fa00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2fa10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2fa20 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2fa30 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2fa40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2fa50 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2fa60 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2fa70 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2fa80 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2fa90 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2faa0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2fab0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2fac0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2fad0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2fae0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2faf0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2fb00 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2fb10 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2fb20 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2fb30 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2fb40 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2fb50 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2fb60 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2fb70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2fb80 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2fb90 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2fba0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2fbb0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2fbc0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2fbd0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2fbe0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2fbf0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2fc00 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2fc10 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2fc20 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2fc30 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2fc40 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2fc50 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2fc60 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2fc70 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2fc80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2fc90 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2fca0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2fcb0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2fcc0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2fcd0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2fce0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2fcf0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2fd00 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2fd10 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2fd20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2fd30 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2fd40 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2fd50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2fd60 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2fd70 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2fd80 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2fd90 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2fda0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2fdb0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2fdc0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2fdd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2fde0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2fdf0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2fe00 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2fe10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2fe20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2fe30 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2fe40 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2fe50 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2fe60 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2fe70 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2fe80 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2fe90 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2fea0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2feb0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2fec0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2fed0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2fee0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2fef0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2ff00 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2ff10 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2ff20 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2ff30 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2ff40 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2ff50 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2ff60 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2ff70 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2ff80 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2ff90 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2ffa0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2ffb0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2ffc0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2ffd0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2ffe0 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
2fff0 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
30000 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
30010 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
30020 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30030 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
30040 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
30050 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
30060 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30070 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
30080 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
30090 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
300a0 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
300b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
300c0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
300d0 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
300e0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
300f0 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
30100 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
30110 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
30120 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
30130 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
30140 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
30150 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
30160 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
30170 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
30180 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
30190 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
301a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
301b0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
301c0 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
301d0 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
301e0 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
301f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
30200 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
30210 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
30220 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
30230 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
30240 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
30250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
30260 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
30270 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
30280 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
30290 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
302a0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
302b0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
302c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
302d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
302e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
302f0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
30300 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
30310 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
30320 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
30330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30340 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
30350 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
30360 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
30370 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
30380 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
30390 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
303a0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
303b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
303c0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
303d0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
303e0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
303f0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
30400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30410 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
30420 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
30430 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
30440 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
30450 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
30460 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
30470 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
30480 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30490 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
304a0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
304b0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
304c0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
304d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
304e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
304f0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
30500 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
30510 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
30520 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
30530 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
30540 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
30550 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
30560 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
30570 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
30580 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
30590 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
305a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
305b0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
305c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
305d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
305e0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
305f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30600 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
30610 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30620 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
30630 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30640 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
30650 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
30660 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
30670 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30680 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
30690 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
306a0 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
306b0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
306c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
306d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
306e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
306f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
30700 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
30710 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
30720 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30730 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
30740 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30750 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
30760 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30770 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
30780 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30790 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
307a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
307b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
307c0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
307d0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
307e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
307f0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
30800 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
30810 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
30820 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
30830 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30840 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
30850 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30860 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
30870 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
30880 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
30890 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
308a0 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
308b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
308c0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
308d0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
308e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
308f0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
30900 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
30910 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
30920 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30930 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
30940 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30950 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
30960 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
30970 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30980 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c  bind_pointer(sql
30990 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
309a0 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68   void*, const ch
309b0 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  ar*,void(*)(void
309c0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
309d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
309e0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
309f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
30a00 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t n);.SQLITE_API
30a10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
30a20 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
30a30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30a40 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
30a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30a60 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
30a70 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
30a80 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30a90 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
30aa0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
30ab0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
30ac0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
30ad0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
30ae0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30af0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
30b00 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
30b10 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
30b20 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
30b30 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
30b40 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
30b50 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
30b60 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
30b70 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
30b80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
30b90 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
30ba0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
30bb0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
30bc0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
30bd0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
30be0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
30bf0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
30c00 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
30c10 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
30c20 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
30c30 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
30c40 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
30c50 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
30c60 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
30c70 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
30c80 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
30c90 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
30ca0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
30cb0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
30cc0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30cd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30ce0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30cf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30d00 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30d10 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
30d20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30d30 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
30d40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30d50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30d60 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
30d70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
30d90 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
30da0 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
30db0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30dc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30dd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30de0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
30df0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
30e00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
30e10 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
30e20 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
30e30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30e40 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
30e50 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
30e60 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
30e70 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
30e80 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
30e90 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
30ea0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
30eb0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
30ec0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
30ed0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
30ee0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
30ef0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
30f00 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
30f10 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
30f20 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
30f30 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
30f40 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
30f50 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
30f60 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
30f70 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
30f80 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
30f90 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
30fa0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
30fb0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
30fc0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
30fd0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
30fe0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
30ff0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
31000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
31010 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
31020 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
31030 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
31040 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
31050 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
31060 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
31070 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
31080 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
31090 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
310a0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
310b0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
310c0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
310d0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
310e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
310f0 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  e16()],.** [sqli
31100 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
31110 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
31120 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
31130 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31140 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
31150 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
31160 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
31170 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31180 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
31190 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
311a0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
311b0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
311c0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
311d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
311e0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
311f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
31200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31210 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
31220 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
31230 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
31240 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31250 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
31260 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
31270 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
31280 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
31290 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
312a0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
312b0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
312c0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
312d0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
312e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
312f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
31300 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
31310 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
31320 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
31330 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
31340 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
31350 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
31360 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
31370 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
31380 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
31390 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
313a0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
313b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
313c0 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  6_v2()] or.** [s
313d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
313e0 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
313f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
31400 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
31410 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
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 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
31440 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31450 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31460 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  name()]..*/.SQLI
31470 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31480 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31490 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
314a0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
314b0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
314c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
314d0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
314e0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
314f0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
31500 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31510 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
31520 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
31530 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
31540 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
31550 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
31560 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
31570 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
31580 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
31590 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
315a0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
315b0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
315c0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
315d0 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
315e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
315f0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
31600 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
31610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31620 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
31630 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31640 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31650 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31660 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
31670 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31680 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31690 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
316a0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
316b0 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69  tement]. ^If thi
316c0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
316d0 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  s 0, that means 
316e0 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
316f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74  d statement] ret
31700 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f  urns no data (fo
31710 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
31720 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65  DATE])..** ^Howe
31730 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73  ver, just becaus
31740 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  e this routine r
31750 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76  eturns a positiv
31760 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f  e number does no
31770 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f  t.** mean that o
31780 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ne or more rows 
31790 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20  of data will be 
317a0 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45  returned.  ^A SE
317b0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a  LECT statement.*
317c0 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61  * will always ha
317d0 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71  ve a positive sq
317e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
317f0 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69  nt() but dependi
31800 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45  ng on the.** WHE
31810 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
31820 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61  aints and the ta
31830 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20  ble content, it 
31840 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20  might return no 
31850 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rows..**.** See 
31860 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
31870 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
31880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
318a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
318b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
318c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
318d0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
318e0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
318f0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31900 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31910 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31920 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
31930 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
31940 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
31950 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
31960 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
31970 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
31980 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
31990 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
319a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
319b0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
319c0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
319d0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
319e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
319f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31a00 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31a10 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
31a20 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
31a30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
31a40 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
31a50 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
31a60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
31a70 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
31a80 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
31a90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
31aa0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
31ab0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
31ac0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
31ad0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
31ae0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31af0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
31b00 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
31b10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31b20 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
31b30 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
31b40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31b50 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
31b60 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
31b70 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
31b80 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
31b90 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
31ba0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
31bb0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
31bc0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
31bd0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
31be0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31bf0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
31c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31c10 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
31c20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
31c30 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
31c40 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
31c50 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
31c60 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
31c70 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
31c80 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
31c90 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
31ca0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
31cb0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
31cc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
31cd0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31ce0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
31cf0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
31d00 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
31d10 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
31d20 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
31d30 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
31d40 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
31d50 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
31d60 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
31d70 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
31d80 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
31d90 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
31da0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
31db0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
31dc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31dd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31de0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31e00 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
31e10 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
31e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31e30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31e40 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
31e50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
31e60 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
31e70 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
31e80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31e90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
31ea0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
31eb0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
31ec0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
31ed0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31ee0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
31ef0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
31f00 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
31f10 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
31f20 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
31f30 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
31f40 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
31f50 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
31f60 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
31f70 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
31f80 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
31f90 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
31fa0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
31fb0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
31fc0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
31fd0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
31fe0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
31ff0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
32000 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
32010 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
32020 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
32030 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
32040 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
32050 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
32060 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
32070 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
32080 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
32090 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
320a0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
320b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
320c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
320d0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
320e0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
320f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32100 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
32110 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
32120 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
32130 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
32140 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
32150 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
32160 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
32170 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
32180 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
32190 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
321a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
321b0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
321c0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
321d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
321e0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
321f0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
32200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32210 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
32220 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
32230 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
32240 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
32250 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
32260 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
32270 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
32280 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
32290 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
322a0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
322b0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
322c0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
322d0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
322e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
322f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
32300 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
32310 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
32320 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
32330 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
32340 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
32350 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
32360 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
32370 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
32380 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
32390 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
323a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
323b0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
323c0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
323d0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
323e0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
323f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32400 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
32410 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
32420 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
32430 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
32440 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
32450 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
32460 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
32470 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
32480 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
32490 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
324a0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
324b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
324c0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
324d0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
324e0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
324f0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
32500 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
32510 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
32520 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
32530 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
32540 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
32550 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
32560 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
32570 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
32580 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
32590 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
325a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
325b0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
325c0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
325d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
325e0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
325f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
32600 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
32610 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
32620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32630 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32640 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
32650 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
32660 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
32670 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32680 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
32690 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
326a0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
326b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
326c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
326d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
326e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
326f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32710 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
32740 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
32750 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
32760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
32770 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
32780 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
32790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
327a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
327b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
327c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
327d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
327e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
327f0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
32800 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32810 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
32820 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32830 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32840 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32850 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
32860 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
32870 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
32880 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
32890 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
328a0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
328b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
328c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
328d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
328e0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
328f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
32900 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
32910 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
32920 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
32930 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
32940 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
32950 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
32960 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
32970 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
32980 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
32990 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
329a0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
329b0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
329c0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
329d0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
329e0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
329f0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
32a00 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
32a10 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
32a20 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
32a30 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
32a40 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
32a50 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
32a60 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
32a70 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
32a80 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
32a90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
32aa0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
32ab0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
32ac0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
32ad0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
32ae0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
32af0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
32b00 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
32b10 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
32b20 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
32b30 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
32b40 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
32b50 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
32b60 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
32b70 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
32b80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
32b90 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
32ba0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
32bb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
32bc0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
32bd0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
32be0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
32bf0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
32c00 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
32c10 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
32c20 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
32c30 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
32c40 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
32c50 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
32c60 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
32c70 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
32c80 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
32c90 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
32ca0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
32cb0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
32cc0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
32cd0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
32ce0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
32cf0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
32d00 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
32d10 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
32d20 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32d30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32d40 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
32d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32d60 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
32d70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32d80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
32d90 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
32da0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
32db0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
32dc0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
32dd0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32de0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32df0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
32e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
32e10 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
32e20 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
32e30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32e40 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
32e50 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
32e60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32e70 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
32e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32e90 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
32ea0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
32eb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
32ec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
32ed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
32ee0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
32ef0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
32f00 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
32f10 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
32f20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
32f30 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
32f40 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
32f50 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
32f60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32f70 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
32f80 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
32f90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
32fa0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
32fb0 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
32fc0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
32fd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
32fe0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32ff0 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
33000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33010 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
33020 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
33030 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
33040 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
33050 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
33060 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
33070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33080 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
33090 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
330a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
330b0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
330c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
330d0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
330e0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
330f0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
33100 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
33110 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
33120 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
33130 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
33140 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
33150 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
33160 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
33170 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
33180 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
33190 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
331a0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
331b0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
331c0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
331d0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
331e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
331f0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
33200 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
33210 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
33220 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
33230 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
33240 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
33250 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
33260 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
33270 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
33280 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
33290 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
332a0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
332b0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
332c0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
332d0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
332e0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
332f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
33300 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
33310 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
33320 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
33330 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
33340 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
33350 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
33360 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
33370 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
33380 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
33390 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
333a0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
333b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
333c0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
333d0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
333e0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
333f0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
33400 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
33410 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
33420 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
33430 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
33440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
33450 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
33460 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
33470 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
33480 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
33490 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
334a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
334b0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
334c0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
334d0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
334e0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
334f0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
33500 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
33510 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
33520 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
33530 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
33540 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
33550 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
33560 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
33570 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
33580 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
33590 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
335a0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
335b0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
335c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
335d0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
335e0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
335f0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
33600 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
33610 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
33620 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
33630 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
33640 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
33650 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
33660 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
33670 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
33680 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
33690 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
336a0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
336b0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
336c0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
336d0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
336e0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
336f0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
33700 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
33710 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
33720 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
33730 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
33740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33750 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
33760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33770 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
33780 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
33790 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
337a0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
337b0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
337c0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
337d0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
337e0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
337f0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
33800 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
33810 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
33820 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
33830 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
33840 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33850 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
33860 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
33870 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
33880 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
33890 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
338a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
338b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
338c0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
338d0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
338e0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
338f0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
33900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33910 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
33920 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
33930 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
33940 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
33950 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
33960 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
33970 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
33980 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
33990 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
339a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
339b0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
339c0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
339d0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
339e0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
339f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
33a00 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
33a10 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
33a20 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
33a30 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
33a40 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
33a50 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
33a60 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
33a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33a80 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
33a90 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
33aa0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
33ab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
33ac0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
33ad0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
33ae0 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
33af0 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
33b00 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
33b10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
33b20 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
33b30 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
33b40 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
33b50 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
33b60 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
33b70 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
33b80 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
33b90 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
33ba0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
33bb0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
33bc0 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
33bd0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
33be0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
33bf0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
33c00 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
33c10 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
33c20 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
33c30 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
33c40 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
33c50 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
33c60 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
33c70 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
33c80 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
33c90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
33ca0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
33cb0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
33cc0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
33cd0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
33ce0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
33cf0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
33d00 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
33d10 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
33d20 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
33d30 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
33d40 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
33d50 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
33d60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33d70 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
33d80 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
33d90 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
33da0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
33db0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
33dc0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
33dd0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
33de0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
33df0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
33e00 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
33e10 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
33e20 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
33e30 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
33e40 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
33e50 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
33e60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33e70 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
33e80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
33e90 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
33ea0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
33eb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33ec0 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
33ed0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
33ee0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
33ef0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
33f00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33f10 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
33f20 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
33f30 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33f40 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
33f50 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
33f60 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
33f70 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
33f80 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
33f90 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
33fa0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
33fb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
33fc0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
33fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33fe0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
33ff0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
34000 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
34010 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
34020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34030 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
34040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
34060 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
34070 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
34080 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
34090 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
340a0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
340b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
340c0 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
340d0 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
340e0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
340f0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
34100 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34110 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
34120 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
34130 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
34140 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
34150 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
34160 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34170 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
34180 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
34190 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
341a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
341b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
341c0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
341d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
341e0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
341f0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
34200 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
34210 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
34220 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
34230 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
34240 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
34250 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
34260 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
34270 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
34280 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
34290 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
342a0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
342b0 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
342c0 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
342d0 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
342e0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
342f0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
34300 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
34310 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
34320 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
34330 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
34340 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
34350 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
34360 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34370 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
34380 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
34390 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
343a0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
343b0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
343c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
343d0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
343e0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
343f0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
34400 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
34410 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
34420 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
34430 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
34440 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
34450 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
34460 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
34470 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
34480 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
34490 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
344a0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
344b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
344c0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
344d0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
344e0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
344f0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
34500 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
34510 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
34520 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
34530 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
34540 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
34550 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
34560 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
34570 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
34580 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
34590 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
345a0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
345b0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
345c0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
345d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
345e0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
345f0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
34600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
34610 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
34620 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
34630 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
34640 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
34650 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
34660 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
34670 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
34680 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
34690 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
346a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
346b0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
346c0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
346d0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
346e0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
346f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34700 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c  te3_stmt.**.** <
34710 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a  b>Summary:</b>.*
34720 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74  * <blockquote><t
34730 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65  able border=0 ce
34740 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c  llpadding=0 cell
34750 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74  spacing=0>.** <t
34760 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34770 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e  _column_blob</b>
34780 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c  <td>&rarr;<td>BL
34790 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  OB result.** <tr
347a0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
347b0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62  column_double</b
347c0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52  ><td>&rarr;<td>R
347d0 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EAL result.** <t
347e0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
347f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c  _column_int</b><
34800 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d  td>&rarr;<td>32-
34810 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
34820 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34830 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34840 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61  int64</b><td>&ra
34850 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e  rr;<td>64-bit IN
34860 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
34870 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34880 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f  e3_column_text</
34890 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
348a0 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
348b0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
348c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
348d0 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61  ext16</b><td>&ra
348e0 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45  rr;<td>UTF-16 TE
348f0 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
34900 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34910 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e  column_value</b>
34920 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68  <td>&rarr;<td>Th
34930 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a  e result as an .
34940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34950 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  e|unprotected sq
34960 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34970 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ect..** <tr><td>
34980 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34990 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74  <td>&nbsp;.** <t
349a0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
349b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62  _column_bytes</b
349c0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53  ><td>&rarr;<td>S
349d0 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a  ize of a BLOB.**
349e0 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 54   or a UTF-8 TEXT
349f0 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73   result in bytes
34a00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34a20 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70  tes16&nbsp;&nbsp
34a30 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61  ;</b>.** <td>&ra
34a40 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  rr;&nbsp;&nbsp;<
34a50 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31  td>Size of UTF-1
34a60 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74  6.** TEXT in byt
34a70 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
34a80 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34a90 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  type</b><td>&rar
34aa0 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a  r;<td>Default.**
34ab0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
34ac0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62   result.** </tab
34ad0 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  le></blockquote>
34ae0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c  .**.** <b>Detail
34af0 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  s:</b>.**.** ^Th
34b00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
34b10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
34b20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
34b30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
34b40 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
34b50 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
34b60 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
34b70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34b80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
34b90 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
34ba0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
34bb0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
34bc0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
34bd0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
34be0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
34bf0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
34c00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
34c10 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
34c20 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
34c30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
34c40 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
34c50 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
34c60 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
34c70 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
34c80 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
34c90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
34ca0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
34cb0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
34cc0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
34cd0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
34ce0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
34cf0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
34d00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
34d10 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
34d20 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
34d30 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
34d40 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
34d50 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
34d60 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
34d70 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
34d80 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
34d90 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
34da0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
34db0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
34dc0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
34dd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
34de0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34df0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
34e00 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
34e10 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
34e20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34e30 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
34e40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
34e50 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
34e60 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
34e70 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
34e80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34e90 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
34ea0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
34eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
34ec0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
34ed0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34ee0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
34ef0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
34f00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
34f10 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
34f20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34f30 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
34f40 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
34f50 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
34f60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34f70 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
34f80 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
34f90 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
34fa0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34fb0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
34fc0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
34fd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34fe0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
34ff0 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
35000 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75  ces (_blob, _dou
35010 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36  ble, _int, _int6
35020 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74  4, _text, and _t
35030 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72  ext16).** each r
35040 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20  eturn the value 
35050 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
35060 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 63  mn in a specific
35070 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49   data format.  I
35080 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20  f.** the result 
35090 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e  column is not in
350a0 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72  itially in the r
350b0 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20  equested format 
350c0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
350d0 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72 65   if the query re
350e0 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
350f0 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 33   but the sqlite3
35100 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
35110 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75  nterface.** is u
35120 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
35130 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61  he value) then a
35140 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  n automatic type
35150 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
35160 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
35170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
35180 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
35190 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
351a0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
351b0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
351c0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
351d0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
351e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
351f0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
35200 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
35210 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
35220 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
35230 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
35240 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
35250 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
35260 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65  TE_NULL]..** The
35270 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35290 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 73  type() can be us
352a0 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 69  ed to decide whi
352b0 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72  ch.** of the fir
352c0 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
352d0 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20   should be used 
352e0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 63  to extract the c
352f0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20  olumn value..** 
35300 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
35310 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35320 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
35330 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
35340 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  f no.** automati
35350 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
35360 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
35370 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69   for the value i
35380 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a  n question.  .**
35390 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
353a0 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65  nversion, the re
353b0 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20  sult of calling 
353c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
353d0 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ype().** is unde
353e0 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61  fined, though ha
353f0 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a  rmless.  Future.
35400 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
35410 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
35420 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
35430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35440 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
35450 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
35460 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
35470 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35480 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73  BLOB or a TEXT s
35490 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  tring, then the 
354a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
354b0 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  ytes().** or sql
354c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
354d0 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 73  s16() interfaces
354e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
354f0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69  determine the si
35500 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c  ze.** of that BL
35510 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
35520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35530 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
35540 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
35550 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
35560 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
35570 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35580 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
35590 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
355a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
355b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
355c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
355d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
355e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
355f0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
35600 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
35610 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
35620 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35630 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
35640 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
35650 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
35660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35670 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
35680 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
35690 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
356a0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
356b0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
356c0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
356d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
356e0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
356f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35700 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
35710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35720 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
35730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35740 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
35750 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
35760 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
35770 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35780 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
35790 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
357a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
357b0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
357c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
357d0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
357e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
357f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35800 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
35810 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
35820 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
35830 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
35840 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
35850 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35860 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
35870 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
35880 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35890 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
358a0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
358b0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
358c0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
358d0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
358e0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
358f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
35900 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35910 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
35920 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
35930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35940 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
35950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
35960 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
35970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35980 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
35990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
359a0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
359b0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
359c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
359d0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
359e0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
359f0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
35a00 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
35a10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35a20 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35a30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35a40 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
35a50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
35a60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
35a70 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
35a80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
35a90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
35aa0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
35ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35ac0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
35ad0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35ae0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
35af0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
35b00 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
35b10 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
35b20 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
35b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35b40 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
35b50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
35b60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35b70 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
35b80 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
35b90 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
35ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35bb0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
35bc0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
35bd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35be0 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
35bf0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
35c00 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
35c10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35c20 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
35c30 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
35c40 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
35c50 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
35c60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35c70 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
35c80 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
35c90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35ca0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
35cb0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
35cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
35cd0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
35ce0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
35cf0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
35d00 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
35d10 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
35d20 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
35d30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
35d40 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
35d50 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
35d60 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
35d70 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
35d80 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20  ..** Hence, the 
35d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
35da0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
35db0 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  .** is normally 
35dc0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68  only useful with
35dd0 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  in the implement
35de0 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70  ation of .** [ap
35df0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35e00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
35e10 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
35e20 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e  les], not within
35e30 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70  .** top-level ap
35e40 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a  plication code..
35e50 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20  **.** The these 
35e60 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74  routines may att
35e70 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
35e80 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 20  the datatype of 
35e90 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  the result..** ^
35ea0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
35eb0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
35ec0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
35ed0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
35ee0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
35ef0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
35f00 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
35f10 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
35f20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
35f30 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
35f40 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
35f50 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
35f60 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
35f70 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
35f80 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
35f90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
35fa0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
35fb0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
35fc0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
35fd0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
35fe0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
35ff0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
36000 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
36010 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
36020 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
36030 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
36040 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
36050 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
36060 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
36070 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
36080 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
36090 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
360a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
360b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
360c0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
360d0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
360e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
360f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
36100 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
36110 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
36120 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
36130 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
36140 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
36150 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
36160 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
36170 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
36180 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
36190 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
361a0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
361b0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
361c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
361d0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
361e0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
361f0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
36200 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
36210 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
36220 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
36230 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
36240 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
36250 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
36260 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
36270 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
36280 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
36290 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
362a0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
362b0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
362c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
362d0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
362e0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
362f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
36300 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
36310 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
36320 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
36330 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
36340 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
36350 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
36360 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
36370 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
36380 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
36390 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
363a0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
363b0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
363c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
363d0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
363e0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
363f0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
36400 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
36410 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
36420 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
36430 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
36440 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
36450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36460 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
36470 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
36480 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36490 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
364a0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
364b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
364c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
364d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
364e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
364f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
36500 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
36510 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
36520 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
36530 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
36540 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
36550 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
36560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36570 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
36580 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
36590 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
365a0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
365b0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
365c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
365d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
365e0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
365f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
36600 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
36610 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
36620 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
36630 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
36640 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
36650 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
36660 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
36670 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
36680 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
36690 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
366a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
366b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
366c0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
366d0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
366e0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
366f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
36700 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
36710 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
36720 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
36730 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
36740 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
36750 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
36760 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
36770 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
36780 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
36790 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
367a0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
367b0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
367c0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
367d0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
367e0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
367f0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
36800 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
36810 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
36820 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
36830 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
36840 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
36850 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
36860 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
36870 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
36880 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
36890 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
368a0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
368b0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
368c0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
368d0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
368e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
368f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36900 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
36910 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
36920 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36930 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
36940 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
36950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36960 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36980 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36990 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
369a0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
369b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
369c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
369d0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
369e0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
369f0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
36a00 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
36a10 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
36a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36a30 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
36a40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
36a50 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
36a60 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
36a70 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
36a80 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
36a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36aa0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
36ab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36ac0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
36ad0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
36ae0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
36af0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
36b00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36b10 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
36b20 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
36b30 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
36b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36b50 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
36b60 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
36b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36b80 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
36b90 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36ba0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
36bc0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
36bd0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
36be0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36bf0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
36c00 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
36c10 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
36c20 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
36c30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
36c40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
36c50 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
36c60 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
36c70 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
36c80 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
36c90 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
36ca0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
36cb0 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68    Do not pass th
36cc0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
36cd0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
36ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36cf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
36d00 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
36d10 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
36d20 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
36d30 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
36d40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
36d50 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
36d60 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
36d70 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
36d80 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
36d90 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
36da0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
36db0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
36dc0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
36dd0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
36de0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
36df0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
36e00 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
36e10 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
36e20 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
36e30 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
36e40 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
36e50 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
36e60 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
36e70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36e80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
36e90 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
36ea0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
36eb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36ec0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
36ed0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36ee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36ef0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
36f00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
36f10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
36f20 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
36f30 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
36f40 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
36f50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36f60 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
36f70 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36f80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
36f90 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
36fa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36fb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
36fc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36fd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36fe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36ff0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
37000 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
37010 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
37020 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
37030 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
37040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37050 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
37060 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
37070 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
37080 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
370a0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
370b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
370c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
370d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
370e0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
370f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
37100 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37110 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
37120 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
37130 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
37140 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
37150 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37160 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
37170 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
37180 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
37190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
371a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
371b0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
371c0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
371d0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
371e0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
371f0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
37200 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
37210 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
37220 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37230 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
37240 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
37250 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
37260 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
37270 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
37280 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
37290 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
372a0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
372b0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
372c0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
372d0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
372e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
372f0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
37300 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
37310 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
37320 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
37330 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
37340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37350 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
37360 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
37370 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
37380 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
37390 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
373a0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
373b0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
373c0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
373d0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
373e0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
373f0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
37400 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
37410 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
37420 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
37430 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
37440 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
37450 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
37460 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
37470 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
37480 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
37490 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
374a0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
374b0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
374c0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
374d0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
374e0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
374f0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
37500 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
37510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
37520 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
37530 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
37540 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
37550 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
37560 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
37570 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
37580 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
37590 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
375a0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
375b0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
375c0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
375d0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
375e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
375f0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
37600 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
37610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37620 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
37630 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
37640 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
37650 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
37660 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
37670 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
37680 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
37690 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
376a0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
376b0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
376c0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
376d0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
376e0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
376f0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
37700 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
37710 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
37720 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
37730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
37740 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
37750 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
37760 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
37770 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
37780 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
37790 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
377a0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
377b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
377c0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
377d0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
377e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
377f0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
37800 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
37810 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
37820 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
37830 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
37840 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
37850 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
37860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37870 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
37880 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
37890 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
378a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
378b0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
378c0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
378d0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
378e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
378f0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
37900 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
37910 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
37920 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
37930 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
37940 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
37950 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
37960 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
37970 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
37980 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
37990 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
379a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
379b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
379c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
379d0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
379e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
379f0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
37a00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
37a10 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
37a20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
37a30 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
37a40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
37a50 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
37a60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
37a70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37a80 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
37a90 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
37aa0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
37ab0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
37ac0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
37ad0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
37ae0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37af0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
37b00 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
37b10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
37b30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
37b50 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
37b60 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
37b70 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
37b80 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
37b90 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
37ba0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
37bb0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
37bc0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
37bd0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
37be0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
37bf0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
37c00 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
37c10 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
37c20 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
37c30 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
37c40 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
37c50 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
37c60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
37c70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37c80 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
37c90 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
37ca0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
37cb0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
37cc0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
37cd0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
37ce0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37cf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
37d00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
37d10 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
37d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
37d30 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
37d40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
37d50 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
37d60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
37d70 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
37d80 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37d90 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
37da0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
37dc0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
37dd0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
37de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
37df0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
37e00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
37e10 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
37e20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
37e30 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
37e40 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
37e50 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
37e60 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
37e70 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
37e80 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
37e90 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
37ea0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
37eb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
37ec0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
37ed0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
37ee0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
37ef0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
37f00 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
37f10 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
37f20 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
37f30 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
37f40 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
37f50 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
37f60 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
37f70 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
37f80 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
37f90 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
37fa0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
37fb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
37fc0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
37fd0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37fe0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
37ff0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
38000 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
38010 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
38020 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
38030 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
38040 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
38050 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
38060 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
38070 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
38080 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
38090 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
380a0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
380b0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
380c0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
380d0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
380e0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
380f0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
38100 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
38110 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
38120 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
38130 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
38140 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
38150 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
38160 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
38170 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
38180 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
38190 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
381a0 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
381b0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
381c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
381d0 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
381e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
381f0 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
38200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
38210 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
38220 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
38230 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
38240 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
38250 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
38260 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
38270 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
38280 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
38290 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
382a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
382b0 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
382c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
382d0 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
382e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
382f0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
38300 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
38310 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
38320 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
38330 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
38340 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
38350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
38360 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
38370 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
38380 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
38390 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
383a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
383b0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
383c0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
383d0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
383e0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
383f0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
38400 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
38410 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
38420 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
38430 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
38440 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
38450 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
38460 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
38470 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
38480 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
38490 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
384a0 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
384b0 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
384c0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
384d0 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
384e0 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
384f0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
38500 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
38510 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
38520 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
38530 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
38540 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
38550 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
38560 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
38570 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
38580 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
38590 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
385a0 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
385b0 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
385c0 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
385d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
385e0 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
385f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
38600 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
38610 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
38620 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
38630 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
38640 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
38650 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
38660 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
38670 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
38680 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
38690 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
386a0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
386b0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
386c0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
386d0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
386e0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
386f0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
38700 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
38710 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
38720 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
38730 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
38740 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
38750 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
38760 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
38770 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38780 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2