/ Hex Artifact Content
Login

Artifact 633ca2147938402fe43118db929a7949dde3e2a08c138e40bbdec12a0e696129:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6910: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6930: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6940: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6950: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6960: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6970: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6980: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6990: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
69a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
69b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
69c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
69d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
69e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
69f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6a00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6a20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6a30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6a60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6a70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6a80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6aa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6ab0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6ac0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6ad0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6ae0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6af0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6b00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6b10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6b20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6b30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6b60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6b70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6b80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ba0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6bb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6bc0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6bd0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6be0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6bf0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6c00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6c20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6c30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6c40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6c50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6c60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6c70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6c80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6ca0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6cb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6cc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6cd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6ce0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6cf0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6d00: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6d10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6d20: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6d30: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6d40: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6d50: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6d60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6d70: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6d80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d90: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6dd0: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6de0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6df0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6e00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6e10: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6e20: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6e30: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6e40: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6e50: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6e60: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6e70: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6e80: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e90: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6eb0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6ec0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6ed0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6ee0: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6ef0: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6f00: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6f10: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6f20: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6f30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6f40: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6f50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6f60: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6f70: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6f80: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f90: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6fa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6fb0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6fc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6fd0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ff0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
7000: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
7030: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7040: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7070: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7090: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
70a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
70b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
70c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
70d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
70e0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
70f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7100: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7110: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7130: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7140: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7150: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7180: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
71a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
71b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
71c0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
71d0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
71e0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
71f0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7210: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7220: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7240: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7250: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7260: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
7270: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
7280: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
72c0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
72d0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
72e0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
72f0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7300: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7310: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7320: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7330: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7340: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7350: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7360: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7370: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
7380: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7390: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
73a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
73c0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
73d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
73e0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7400: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7420: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7430: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7440: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7450: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7460: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
7470: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
7480: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7490: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
74a0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
74b0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
74c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
74d0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
74e0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
74f0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7500: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7520: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7550: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7560: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
7570: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
7580: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7590: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
75a0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
75b0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
75c0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
75d0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
75e0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
75f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7610: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7620: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7630: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7640: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7650: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7660: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
7670: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
7680: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7690: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
76a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
76b0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
76c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
76d0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
76e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
76f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7700: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7710: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7720: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7730: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7740: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7750: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7760: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7770: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7780: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7790: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
77a0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
77b0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
77c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
77d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
77e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
77f0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7800: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7810: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7820: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7830: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7840: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7850: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7860: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7870: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7880: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7890: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
78a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
78b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
78c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
78d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
78e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
78f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7900: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7910: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7920: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7930: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7940: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7950: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7960: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7980: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7990: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
79a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
79b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
79c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
79d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
79f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7a00: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7a10: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7a50: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7a70: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7a80: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a90: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7ab0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7ac0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7ad0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7ae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7af0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7b00: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7b10: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7b20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7b30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7b40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7b50: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7b60: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7b70: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7b80: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b90: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7bb0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7bc0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7bd0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7be0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7c00: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7c10: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7c20: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7c30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7c40: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7c50: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7c60: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7c70: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c90: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7ca0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7cd0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7ce0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7d00: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7d10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7d20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7d30: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7d40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7d50: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7d60: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7d70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7d80: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d90: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7da0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7db0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7dc0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7de0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7df0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e00: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7e10: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7e20: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7e30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7e40: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7e50: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7e60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7e70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e80: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e90: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7ea0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7eb0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7ec0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7ed0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7ee0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7ef0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7f00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7f10: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7f20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7f30: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7f40: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f60: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7f70: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7f80: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f90: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7fa0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7fb0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7fc0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7fd0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7fe0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7ff0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
8000: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
8010: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
8020: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
8030: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
8040: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
8050: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
8060: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
8070: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
8080: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8090: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
80a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
80b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
80c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
80d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8100: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8120: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8130: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8140: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8150: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8160: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
8170: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
8180: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8190: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
81a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
81b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
81c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
81d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
81e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
81f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8200: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8210: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8220: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8230: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8240: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8250: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8260: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
8270: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
8280: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8290: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
82a0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
82c0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
82d0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
82e0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
82f0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8310: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8320: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8330: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8340: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8350: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8360: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
8370: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
8380: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8390: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
83a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
83b0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
83c0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
83d0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
83e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
83f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8400: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8410: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8420: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8430: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8440: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8450: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8460: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
8470: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
8480: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8490: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
84a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
84b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
84c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
84d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
84e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
84f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8500: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8510: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8520: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8530: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8540: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8550: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8560: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
8570: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
8580: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8590: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
85a0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
85b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
85c0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
85d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
85e0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
85f0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8600: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8610: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8630: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8640: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8650: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8660: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
8670: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
8680: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8690: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
86a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
86b0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
86c0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
86d0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
86e0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
86f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8700: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8710: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8720: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8730: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8740: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8750: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8760: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8770: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
8780: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8790: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
87a0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
87b0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
87c0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
87d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8810: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8830: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8890: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
88a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
88b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
88e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8910: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8920: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8930: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8960: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
8980: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8990: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
89a0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
89b0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
89c0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
89d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
89e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
89f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8a00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8a10: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8a20: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8a30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8a60: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8a70: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8a80: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a90: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8aa0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8ab0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8ac0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8ad0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8ae0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8b00: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8b10: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8b20: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b30: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8b40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b50: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8b60: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8b70: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8b80: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b90: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ba0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8bb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8bd0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8be0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8bf0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8c00: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8c10: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8c20: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8c30: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8c40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8c50: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8c60: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8c70: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8c80: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c90: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8ca0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8cb0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8cc0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8cd0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8ce0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8cf0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d00: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8d10: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8d20: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8d30: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8d50: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8d70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8d80: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d90: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8da0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8db0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8dc0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8dd0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8de0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8df0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8e00: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8e10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8e20: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8e30: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8e40: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8e50: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e70: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ea0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8eb0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8ee0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8ef0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8f00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8f10: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8f20: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8f30: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8f40: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8f50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8f60: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8f70: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f90: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8fa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8fb0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8fc0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8fd0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8fe0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8ff0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9000: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9010: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9020: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9030: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9040: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9050: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9060: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9070: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9080: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9090: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
90a0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
90b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
90c0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
90d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
90e0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9100: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9110: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9120: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9130: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9140: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9160: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9170: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9180: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9190: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
91a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
91b0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
91c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91e0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
91f0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9200: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9210: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9220: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9230: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9240: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9250: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9260: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
9270: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
9280: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9290: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
92a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
92b0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
92c0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
92d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
92e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
92f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9300: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9330: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9360: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9370: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9380: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9390: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
93a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
93b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
93c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
93d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
93e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
93f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9400: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9410: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9420: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9430: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9440: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9450: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9460: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9470: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
9480: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9490: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
94a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
94b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
94c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
94d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
94e0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
94f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9500: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9510: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9520: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9540: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9560: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
9570: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
9580: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9590: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
95a0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
95b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
95c0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
95d0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
95e0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
95f0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9600: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9610: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9620: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9630: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9640: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9650: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9660: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9670: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9680: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9690: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
96a0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
96b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
96c0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
96d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
96e0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d  E_FCNTL_SIZE_LIM
96f0: 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  IT]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c  ITE_FCNTL_SIZE_L
9710: 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  IMIT] opcode is 
9720: 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f 72  used by in-memor
9730: 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69 6d  y VFS that.** im
9740: 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74 65  plements [sqlite
9750: 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d  3_deserialize()]
9760: 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65 72   to set an upper
9770: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
9780: 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e 2d  ze.** of the in-
9790: 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e  memory database.
97a0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
97b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
97c0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
97d0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
97e0: 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  ger pointed to i
97f0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9800: 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69 6e   it is filled in
9810: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75 72   with the.** cur
9820: 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74 68  rent limit.  Oth
9830: 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69 74  erwise the limit
9840: 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20 6c   is set to the l
9850: 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61 6c  arger of the val
9860: 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e 74  ue.** of the int
9870: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9880: 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
9890: 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20 20  database size.  
98a0: 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 70  The integer.** p
98b0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65 74  ointed to is set
98c0: 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d 69   to the new limi
98d0: 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  t..**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
98f0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
9900: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
9910: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
9920: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
9930: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
9940: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
9950: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
9960: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
9970: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
9980: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
9990: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
99a0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
99b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
99c0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
99d0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
99e0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
99f0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
9a00: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
9a10: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
9a20: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
9a30: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
9a40: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
9a50: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
9a60: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
9a70: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
9a80: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
9a90: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
9aa0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
9ab0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
9ac0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9ad0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ae0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9af0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9b10: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9b20: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9b30: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9b40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9b50: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9b70: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9b80: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9b90: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9ba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9bb0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  AL_POINTER]..**.
9bc0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9bd0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9be0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9bf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9c00: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  RNAL_POINTER] op
9c10: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9c20: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
9c30: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
9c40: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
9c50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
9c60: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c   the journal fil
9c70: 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65  e (either.** the
9c80: 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e   [rollback journ
9c90: 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74  al] or the [writ
9ca0: 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f  e-ahead log]) fo
9cb0: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  r a particular d
9cc0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9cd0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9ce0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9cf0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  ILE_POINTER]..**
9d00: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9d10: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
9d20: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
9d30: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
9d40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9d50: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
9d60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9d70: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9d80: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9d90: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9da0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9db0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9dc0: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9dd0: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9de0: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9df0: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9e00: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9e10: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9e20: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
9e30: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9e40: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9e50: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
9e60: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
9e70: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9e80: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9e90: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9ea0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9eb0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9ec0: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9ed0: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9ee0: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9ef0: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9f00: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9f10: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
9f20: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
9f30: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9f40: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9f50: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
9f60: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
9f70: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9f80: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9f90: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9fa0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9fb0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9fc0: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9fd0: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9fe0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9ff0: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
a000: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
a010: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
a020: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
a030: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
a040: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a050: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
a060: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
a070: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
a080: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
a090: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
a0a0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
a0b0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
a0c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a0d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
a0e0: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
a0f0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
a100: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
a110: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
a120: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
a130: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
a140: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
a150: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
a160: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
a170: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
a180: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
a190: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
a1a0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
a1b0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
a1c0: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
a1d0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
a1e0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
a1f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
a200: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
a210: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a220: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
a230: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
a240: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
a250: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
a260: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
a270: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
a280: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
a290: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
a2a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
a2b0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
a2c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a2d0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
a2e0: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
a2f0: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
a300: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
a310: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
a320: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
a330: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
a340: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
a350: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
a360: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
a370: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
a380: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
a390: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
a3a0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
a3b0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
a3c0: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
a3d0: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
a3e0: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
a3f0: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
a400: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
a410: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
a420: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
a430: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
a440: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
a450: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
a460: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
a470: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
a480: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
a490: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
a4a0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
a4b0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
a4c0: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
a4d0: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
a4e0: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
a4f0: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
a500: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
a510: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
a520: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
a530: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
a540: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
a550: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
a560: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
a570: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
a580: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
a590: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
a5a0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
a5b0: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65  nteger is the ne
a5c0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
a5d0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
a5e0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
a5f0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
a600: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
a610: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
a620: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
a630: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
a640: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
a650: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
a660: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
a670: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
a680: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
a690: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
a6a0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
a6b0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
a6c0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
a6d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
a6e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
a6f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a700: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a730: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a740: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a750: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a760: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
a770: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
a780: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
a790: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
a7a0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
a7b0: 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61 6e   ([WAL file]) an
a7c0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 0a  d shared memory.
a7d0: 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ** files used fo
a7e0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
a7f0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
a800: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
a810: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
a820: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
a830: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
a840: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
a850: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
a860: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
a870: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
a880: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
a890: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
a8a0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
a8b0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
a8c0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
a8d0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
a8e0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
a8f0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
a900: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
a910: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
a920: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
a930: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
a940: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
a950: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a960: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
a970: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
a980: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
a990: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
a9a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a9b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a9c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a9d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a9e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a9f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
aa00: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
aa10: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
aa20: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
aa30: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
aa40: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
aa50: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
aa60: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
aa70: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
aa80: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
aa90: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
aaa0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
aab0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
aac0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aad0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
aae0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
aaf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ab00: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ab10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
ab20: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
ab30: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
ab40: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
ab50: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
ab60: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
ab70: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
ab80: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
ab90: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
aba0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
abb0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
abc0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
abd0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
abe0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
abf0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
ac00: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ac10: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
ac20: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
ac30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
ac40: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
ac50: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
ac60: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
ac70: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
ac80: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
ac90: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
aca0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
acb0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
acc0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
acd0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
ace0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
acf0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ad00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ad10: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
ad20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ad30: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
ad40: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
ad50: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
ad60: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
ad70: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
ad80: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
ad90: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
ada0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
adb0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
adc0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
add0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
ade0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
adf0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
ae00: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
ae10: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
ae20: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
ae30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ae40: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
ae50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ae60: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
ae70: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
ae80: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
ae90: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
aea0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
aeb0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
aec0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
aed0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
aee0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
aef0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
af00: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
af10: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
af20: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
af30: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
af40: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
af50: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
af60: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
af70: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
af80: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
af90: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
afa0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
afb0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
afc0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
afd0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
afe0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
aff0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
b000: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
b010: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
b020: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
b030: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
b040: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
b050: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
b060: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
b070: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
b080: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
b090: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
b0a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b0b0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
b0c0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
b0d0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
b0e0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
b0f0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
b100: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b110: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
b120: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b130: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b140: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69  INTER] opcode fi
b150: 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  nds a pointer to
b160: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a   the top-level.*
b170: 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e  * [VFSes] curren
b180: 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54  tly in use.  ^(T
b190: 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e  he argument X in
b1a0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  .** sqlite3_file
b1b0: 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49  _control(db,SQLI
b1c0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
b1d0: 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a  NTER,X) must be.
b1e0: 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c  ** of type "[sql
b1f0: 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20  ite3_vfs] **".  
b200: 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c  This opcodes wil
b210: 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61  l set *X.** to a
b220: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
b230: 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e  top-level VFS.)^
b240: 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20  .** ^When there 
b250: 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53  are multiple VFS
b260: 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74   shims in the st
b270: 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65  ack, this opcode
b280: 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70   finds the.** up
b290: 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e  per-most shim on
b2a0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
b2b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b2c0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
b2d0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
b2e0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
b2f0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
b300: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
b310: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b320: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
b330: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
b340: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
b350: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
b360: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
b370: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
b380: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
b390: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
b3a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
b3b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b3c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b3d0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
b3e0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
b3f0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
b400: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
b410: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
b420: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
b430: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
b440: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
b450: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
b470: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
b480: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
b490: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
b4a0: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
b4b0: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
b4c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b4d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
b4e0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
b4f0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
b500: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
b510: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
b520: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
b530: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b540: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
b550: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
b560: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
b570: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
b580: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
b590: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
b5a0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
b5b0: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
b5c0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
b5d0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
b5e0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
b5f0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
b600: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b610: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
b620: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
b630: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
b640: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b650: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b660: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b670: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
b680: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
b690: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
b6a0: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
b6b0: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
b6c0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
b6d0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
b6e0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
b6f0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
b700: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
b710: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
b720: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
b730: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
b740: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
b750: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
b760: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
b770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b780: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b790: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
b7a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
b7b0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
b7c0: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
b7d0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
b7e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
b7f0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
b800: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
b810: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
b820: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
b830: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
b840: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
b850: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
b860: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b870: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
b880: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
b890: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
b8a0: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
b8b0: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
b8c0: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
b8d0: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
b8e0: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
b8f0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
b900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b910: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b920: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
b930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b940: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
b950: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
b960: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
b970: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
b980: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
b990: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
b9a0: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
b9b0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
b9c0: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
b9d0: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
b9e0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
b9f0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
ba00: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
ba10: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
ba20: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
ba30: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
ba40: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
ba50: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
ba60: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
ba70: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
ba80: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
ba90: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
baa0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
bab0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
bac0: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
bad0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
bae0: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
baf0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
bb00: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
bb10: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
bb20: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
bb30: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
bb40: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
bb50: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
bb60: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
bb70: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bb80: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
bb90: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
bba0: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
bbb0: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
bbc0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bbd0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bbe0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
bbf0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
bc00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
bc10: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
bc20: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
bc30: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
bc40: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
bc50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bc60: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
bc70: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
bc80: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
bc90: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
bca0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
bcb0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
bcc0: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
bcd0: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
bce0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
bcf0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
bd00: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
bd10: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
bd20: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
bd30: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
bd40: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
bd50: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
bd60: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
bd70: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
bd80: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
bd90: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
bda0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
bdb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bdc0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
bdd0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bde0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
bdf0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
be00: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
be10: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
be20: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
be30: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
be40: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
be50: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
be60: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
be70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
be80: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
be90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
bea0: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
beb0: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
bec0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
bed0: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
bee0: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
bef0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
bf00: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
bf10: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
bf20: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
bf30: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
bf40: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
bf50: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
bf60: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
bf70: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
bf80: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
bf90: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
bfa0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
bfb0: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
bfc0: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
bfd0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
bfe0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
bff0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
c000: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
c010: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c020: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
c030: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c040: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
c050: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
c060: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
c070: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
c080: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
c090: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
c0a0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
c0b0: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
c0c0: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
c0d0: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
c0e0: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
c0f0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
c100: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
c110: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
c120: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
c130: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
c140: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
c150: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
c160: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
c170: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c180: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
c190: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
c1a0: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
c1b0: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
c1c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
c1e0: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
c1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c200: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
c210: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c220: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c230: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
c240: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
c250: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
c260: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
c270: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
c280: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
c290: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
c2a0: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
c2b0: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
c2c0: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
c2d0: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
c2e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c2f0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
c300: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
c310: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c320: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
c330: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c340: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c350: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
c360: 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  g native file ha
c370: 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  ndle associated 
c380: 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64  with a file hand
c390: 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a  le.  This file.*
c3a0: 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  * control interp
c3b0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c3c0: 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t as a pointer t
c3d0: 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20  o a native file 
c3e0: 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72  handle and.** wr
c3f0: 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69  ites the resulti
c400: 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a  ng value there..
c410: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c430: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
c440: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c450: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c460: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
c470: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
c480: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
c490: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
c4a0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
c4b0: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
c4c0: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
c4d0: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
c4e0: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
c4f0: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
c500: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
c510: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
c520: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
c530: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
c540: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
c550: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
c560: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c580: 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CK]].** The [SQL
c590: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5a0: 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c  OCK] is a signal
c5b0: 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65   to the VFS laye
c5c0: 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a  r that it might.
c5d0: 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f  ** be advantageo
c5e0: 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74  us to block on t
c5f0: 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b  he next WAL lock
c600: 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20   if the lock is 
c610: 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  not immediately.
c620: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  ** available.  T
c630: 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d  he WAL subsystem
c640: 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67   issues this sig
c650: 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a  nal during rare.
c660: 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  ** circumstances
c670: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78   in order to fix
c680: 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20   a problem with 
c690: 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69  priority inversi
c6a0: 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  on..** Applicati
c6b0: 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e  ons should <em>n
c6c0: 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73  ot</em> use this
c6d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a   file-control..*
c6e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c6f0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d  E_FCNTL_ZIPVFS]]
c700: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c710: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70  FCNTL_ZIPVFS] op
c720: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c730: 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e  ted by zipvfs on
c740: 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a  ly. All other.**
c750: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c760: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c770: 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  ND for this opco
c780: 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  de..**.** <li>[[
c790: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c7a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c7b0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63  E_FCNTL_RBU] opc
c7c0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c7d0: 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61  ed by the specia
c7e0: 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a  l VFS used by.**
c7f0: 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69   the RBU extensi
c800: 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74  on only.  All ot
c810: 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72  her VFS should r
c820: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c830: 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69  FOUND for.** thi
c840: 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  s opcode.  .**.*
c850: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c860: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c870: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20  C_WRITE]].** If 
c880: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c890: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c8a0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74  RITE] opcode ret
c8b0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20  urns SQLITE_OK, 
c8c0: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65  then.** the file
c8d0: 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70   descriptor is p
c8e0: 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20  laced in "batch 
c8f0: 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69  write mode", whi
c900: 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20  ch.** means all 
c910: 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65  subsequent write
c920: 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c   operations will
c930: 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64   be deferred and
c940: 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61   done.** atomica
c950: 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20  lly at the next 
c960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c970: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c980: 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20  E].  Systems.** 
c990: 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70  that do not supp
c9a0: 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63  ort batch atomic
c9b0: 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74   writes will ret
c9c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c9d0: 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69  UND..** ^Followi
c9e0: 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  ng a successful 
c9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ca00: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IN_ATOMIC_WRITE 
ca10: 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20  and prior to.** 
ca20: 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c  the closing [SQL
ca30: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ca40: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ca50: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  r.** [SQLITE_FCN
ca60: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
ca70: 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74  IC_WRITE], SQLit
ca80: 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e  e will make.** n
ca90: 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  o VFS interface 
caa0: 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d  calls on the sam
cab0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
cac0: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
cad0: 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63  .** except for c
cae0: 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69  alls to the xWri
caf0: 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68  te method and th
cb00: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
cb10: 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53  ethod.** with [S
cb20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
cb30: 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _HINT]..**.** <l
cb40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
cb50: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cb60: 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RITE]].** The [S
cb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
cb80: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
cb90: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61   opcode causes a
cba0: 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72  ll write.** oper
cbb0: 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65  ations since the
cbc0: 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73   previous succes
cbd0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a  sful call to .**
cbe0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
cbf0: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
cc00: 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d  E] to be perform
cc10: 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a  ed atomically..*
cc20: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
cc30: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
cc40: 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f  ITE_OK] if and o
cc50: 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65  nly if the write
cc60: 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65  s were.** all pe
cc70: 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66  rformed successf
cc80: 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65  ully and have be
cc90: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20  en committed to 
cca0: 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61  persistent stora
ccb0: 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  ge..** ^Regardle
ccc0: 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
ccd0: 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65   not it is succe
cce0: 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65  ssful, this file
ccf0: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a   control takes.*
cd00: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
cd10: 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74  iptor out of bat
cd20: 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f  ch write mode so
cd30: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
cd40: 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70  uent.** write op
cd50: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64  erations are ind
cd60: 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51  ependent..** ^SQ
cd70: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
cd80: 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43  invoke SQLITE_FC
cd90: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
cda0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
cdb0: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
cdc0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
cdd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
cde0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
cdf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ce00: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
ce10: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  CK_ATOMIC_WRITE]
ce20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ce30: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
ce40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
ce50: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
ce60: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
ce70: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
ce80: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
ce90: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
cea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
ceb0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
cec0: 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  to be rolled bac
ced0: 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65  k..** ^This file
cee0: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74   control takes t
cef0: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cf00: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cf10: 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f  write mode.** so
cf20: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
cf30: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
cf40: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cf50: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cf60: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cf70: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cf80: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cf90: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
cfa0: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
cfb0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
cfc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cfd0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
cfe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cff0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
d000: 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MEOUT]].** The [
d010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d020: 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64  K_TIMEOUT] opcod
d030: 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70 74  e causes attempt
d040: 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  s to obtain.** a
d050: 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67   file lock using
d060: 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53   the xLock or xS
d070: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f  hmLock methods o
d080: 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61 69  f the VFS to wai
d090: 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d  t.** for up to M
d0a0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
d0b0: 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77 68  fore failing, wh
d0c0: 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69 6e  ere M is the sin
d0d0: 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64  gle .** unsigned
d0e0: 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 74   integer paramet
d0f0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
d100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
d110: 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54  A_VERSION]].** T
d120: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d130: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 6f  _DATA_VERSION] o
d140: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
d150: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d160: 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73 65  to.** a database
d170: 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67 75   file.  The argu
d180: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
d190: 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75 6e  r to a 32-bit un
d1a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
d1b0: 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65 72  ** The "data ver
d1c0: 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70 61  sion" for the pa
d1d0: 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69  ger is written i
d1e0: 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72 2e  nto the pointer.
d1f0: 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20 76    The.** "data v
d200: 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73 20  ersion" changes 
d210: 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68 61  whenever any cha
d220: 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74 68  nge occurs to th
d230: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
d240: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
d250: 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67 68  , either through
d260: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
d270: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
d280: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
d290: 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74 72  on or through tr
d2a0: 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d 69  ansactions commi
d2b0: 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74 65  tted by separate
d2c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
d2d0: 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 6c  nections possibl
d2e0: 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  y in other proce
d2f0: 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 74  sses. The [sqlit
d300: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
d310: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
d320: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d330: 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74 61  find if any data
d340: 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e 6e  base on the conn
d350: 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e 67  ection has chang
d360: 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 20  ed,.** but that 
d370: 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e  interface respon
d380: 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f 6e  ds to changes on
d390: 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 73   TEMP as well as
d3a0: 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a 2a   MAIN and does.*
d3b0: 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  * not provide a 
d3c0: 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74  mechanism to det
d3d0: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20 4d  ect changes to M
d3e0: 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c  AIN only.  Also,
d3f0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
d400: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
d410: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70  ] interface resp
d420: 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61 6c  onds to internal
d430: 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 6e   changes only an
d440: 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e 67  d.** omits chang
d450: 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65 72  es made by other
d460: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d470: 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 5b  tions.  The.** [
d480: 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73  PRAGMA data_vers
d490: 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 6f  ion] command pro
d4a0: 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73 6d  vide a mechanism
d4b0: 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67   to detect chang
d4c0: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c  es to.** a singl
d4d0: 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
d4e0: 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20 64  ase that occur d
d4f0: 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74 61  ue to other data
d500: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d510: 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 63  ,.** but omits c
d520: 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e 74  hanges implement
d530: 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
d540: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e  se connection on
d550: 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a 20   which it is.** 
d560: 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 69  called.  This fi
d570: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 68  le control is th
d580: 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 6d  e only mechanism
d590: 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67   to detect chang
d5a0: 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 65  es that.** happe
d5b0: 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61  n either interna
d5c0: 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c 6c  lly or externall
d5d0: 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20 61  y and that are a
d5e0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
d5f0: 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  * a particular a
d600: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
d610: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  ..** </ul>.*/.#d
d620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d630: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
d640: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
d650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d660: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
d670: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
d680: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d690: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
d6a0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
d6b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d6c0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
d6d0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
d6e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d6f0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
d700: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
d710: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
d720: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
d730: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
d740: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
d750: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
d760: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
d770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d780: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
d790: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
d7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d7b0: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
d7c0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
d7d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
d7e0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
d7f0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
d800: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
d810: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
d820: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
d830: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
d840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d850: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
d860: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
d870: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
d880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d890: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
d8b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d8c0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
d8d0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
d8e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d8f0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
d900: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
d910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d920: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
d930: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
d940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d950: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
d960: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
d970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d980: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
d990: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
d9a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d9b0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
d9c0: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
d9d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d9e0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
d9f0: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
da00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
da10: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
da20: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
da30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
da40: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
da50: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
da60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
da70: 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  FS              
da80: 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51     25.#define SQ
da90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20  LITE_FCNTL_RBU  
daa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dab0: 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    26.#define SQL
dac0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
dad0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
dae0: 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   27.#define SQLI
daf0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
db00: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
db10: 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  28.#define SQLIT
db20: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
db30: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
db40: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
db50: 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20  _FCNTL_PDB      
db60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30                30
db70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
db90: 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a  IC_WRITE     31.
dba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dbb0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
dbc0: 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23  IC_WRITE    32.#
dbd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dbe0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64  MIC_WRITE  33.#d
dc00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dc10: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20  TL_LOCK_TIMEOUT 
dc20: 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64 65            34.#de
dc30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dc40: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20 20  L_DATA_VERSION  
dc50: 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65 66           35.#def
dc60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dc70: 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20 20  _SIZE_LIMIT     
dc80: 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20 64          36../* d
dc90: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
dca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dcb0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
dcc0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
dcd0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
dce0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
dcf0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
dd00: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
dd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
dd20: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
dd30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
dd40: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
dd50: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
dd60: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
dd70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
dd80: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
dd90: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
dda0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
ddb0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
ddc0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
ddd0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
dde0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
ddf0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
de00: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
de10: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
de20: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
de30: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
de40: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
de50: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
de60: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
de70: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
de80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
de90: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
dea0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
deb0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
dec0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
ded0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
dee0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
def0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
df00: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
df10: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
df20: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
df30: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
df40: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
df50: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
df60: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
df70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
df80: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
df90: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
dfa0: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
dfb0: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
dfc0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
dfd0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
dfe0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
dff0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
e000: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
e010: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e020: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
e030: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
e040: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
e050: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
e060: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
e070: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
e080: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e090: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
e0a0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
e0b0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
e0c0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
e0d0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
e0e0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
e0f0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
e100: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
e110: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
e120: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
e130: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
e140: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
e150: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
e160: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
e170: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
e180: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
e190: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78   is sometimes ex
e1a0: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67  tended by adding
e1b0: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74   new methods ont
e1c0: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45  o.** the end.  E
e1d0: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e  ach time such an
e1e0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72   extension occur
e1f0: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  s, the iVersion 
e200: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72  field.** is incr
e210: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56  emented.  The iV
e220: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61  ersion value sta
e230: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e  rted out as 1 in
e240: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e250: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64  ion 3.5.0] on [d
e260: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68  ateof:3.5.0], th
e270: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20  en increased to 
e280: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65  2.** with SQLite
e290: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d   [version 3.7.0]
e2a0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
e2b0: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63  0], and then inc
e2c0: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77  reased.** to 3 w
e2d0: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73  ith SQLite [vers
e2e0: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64  ion 3.7.6] on [d
e2f0: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41  ateof:3.7.6].  A
e300: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
e310: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e  .** may be appen
e320: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ded to the sqlit
e330: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e  e3_vfs object an
e340: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  d the iVersion v
e350: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72  alue.** may incr
e360: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75  ease again in fu
e370: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e380: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65   SQLite..** Note
e390: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
e3a0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
e3b0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
e3c0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
e3d0: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a  transition from.
e3e0: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
e3f0: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65  on 3.5.9] to [ve
e400: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20  rsion 3.6.0] on 
e410: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a  [dateof:3.6.0].*
e420: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  * and yet the iV
e430: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
e440: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a   not modified..*
e450: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e460: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e470: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e480: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e490: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e4a0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e4b0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e4c0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e4d0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e4e0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e4f0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e500: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e510: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e520: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e530: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e540: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e550: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e560: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e580: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e590: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e5a0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e5b0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e5c0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e5d0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e5e0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e5f0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e600: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e610: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e620: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e640: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e650: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e660: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e670: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e680: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e690: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e6a0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e6b0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e6c0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e6d0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e6e0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e6f0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e700: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e710: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e720: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e730: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e740: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e750: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e760: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e780: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e790: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e7a0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e7b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e7c0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e7d0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e7e0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e7f0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e800: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e810: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e820: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e830: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e840: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e850: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
e860: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
e870: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
e880: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
e890: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
e8a0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
e8b0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
e8c0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
e8d0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
e8e0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
e8f0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
e900: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
e910: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
e920: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
e930: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
e940: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
e950: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
e960: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
e970: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
e980: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
e990: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
e9a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
e9b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
e9c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
e9d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
e9e0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
e9f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ea00: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ea10: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ea20: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ea30: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ea40: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ea50: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ea60: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ea70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ea80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ea90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
eaa0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
eab0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
eac0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ead0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
eae0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
eaf0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
eb00: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
eb10: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
eb20: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
eb30: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
eb40: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
eb50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
eb60: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
eb70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
eb80: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
eb90: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
eba0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ebb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ebc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ebd0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ebe0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ebf0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
ec00: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
ec10: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
ec20: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
ec30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
ec40: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
ec50: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
ec60: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
ec70: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
ec80: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
ec90: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
eca0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ecb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
ecc0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
ecd0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
ece0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
ecf0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
ed00: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
ed10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
ed20: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
ed30: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
ed40: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
ed50: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
ed60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
ed70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ed80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
ed90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
eda0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
edb0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
edc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
edd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ede0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
edf0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ee00: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
ee10: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
ee20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
ee30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ee40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
ee50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
ee60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ee70: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
ee80: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
ee90: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
eea0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
eeb0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
eec0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
eed0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
eee0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
eef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
ef00: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
ef10: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
ef20: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
ef30: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
ef40: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
ef50: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
ef60: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
ef70: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
ef80: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
ef90: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
efa0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
efb0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
efc0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
efd0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
efe0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
eff0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
f000: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
f010: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
f020: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
f030: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
f040: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
f050: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
f060: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
f070: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
f080: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
f090: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
f0a0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
f0b0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
f0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
f0d0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
f0e0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
f0f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
f100: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f110: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
f120: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f130: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
f140: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
f150: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f160: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
f170: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f180: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
f190: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
f1a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
f1b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f1c0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
f1d0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f1e0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f1f0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f200: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f210: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f230: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f240: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f250: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f260: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f280: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f290: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f2a0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f2b0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f2c0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f2d0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f2e0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f2f0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f300: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f310: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f320: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f330: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f350: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f360: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f370: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f380: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f390: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f3a0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f3b0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f3c0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f3d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f3e0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f3f0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f400: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f410: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f420: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f430: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f440: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f460: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f470: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f480: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f490: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f4a0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f4b0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f4c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f4d0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f4e0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f4f0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f500: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f510: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f520: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f530: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f540: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f560: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f570: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f580: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f590: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f5a0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f5b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f5c0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f5d0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f5e0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f5f0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f600: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f610: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f620: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f630: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f640: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f650: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f660: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f670: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f680: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f690: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f6a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f6b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f6c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f6d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f6e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f6f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f700: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f720: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f730: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f740: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f750: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f760: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f770: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f790: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f7a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f7b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f7c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f7d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f7e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f7f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f800: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f810: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f820: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f830: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f840: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f850: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
f860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
f870: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
f880: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
f890: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
f8a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
f8b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
f8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
f8d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
f8e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
f8f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
f900: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
f910: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
f920: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
f930: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
f940: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
f950: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
f960: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f970: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
f980: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
f990: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
f9a0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
f9b0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
f9c0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
f9d0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
f9e0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
f9f0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
fa00: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
fa10: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
fa20: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
fa30: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
fa40: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
fa50: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
fa60: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
fa70: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
fa80: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
fa90: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
faa0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
fab0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
fac0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
fad0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
fae0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
faf0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
fb00: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
fb10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
fb20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
fb30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
fb40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
fb50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
fb60: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
fb70: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
fb80: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
fb90: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fba0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
fbb0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
fbc0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
fbd0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fbe0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fbf0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fc00: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fc10: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fc20: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fc30: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fc40: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fc50: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fc60: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fc70: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
fc80: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fc90: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fca0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fcb0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fcc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fcd0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fce0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fcf0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fd00: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
fd10: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fd20: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fd30: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fd40: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
fd50: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
fd60: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
fd70: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
fd80: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
fd90: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
fda0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
fdb0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
fdc0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
fdd0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
fde0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
fdf0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
fe00: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
fe10: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
fe20: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
fe30: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
fe40: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
fe50: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
fe60: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
fe70: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
fe80: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
fe90: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
fea0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
feb0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
fec0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
fed0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
fee0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
fef0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
ff00: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
ff10: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
ff20: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
ff30: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
ff40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
ff50: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
ff60: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
ff70: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
ff80: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
ff90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
ffa0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
ffb0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
ffc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
ffd0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
ffe0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
fff0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
10000 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
10010 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
10020 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
10030 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
10040 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
10050 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
10060 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10070 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
10080 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
10090 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
100a0 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
100b0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
100c0 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
100d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
100e0 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
100f0 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
10100 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
10110 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
10120 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
10130 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
10140 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
10150 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
10160 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
10170 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
10180 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
10190 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
101a0 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
101b0 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
101c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
101d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
101e0 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
101f0 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
10200 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10210 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
10220 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
10230 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
10240 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
10250 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
10260 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10270 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
10280 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
10290 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
102a0 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
102b0 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
102c0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
102d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
102e0 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
102f0 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
10300 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10310 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10320 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10330 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
10340 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
10350 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10370 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
10380 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
10390 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
103a0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
103b0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
103c0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
103d0 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
103e0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
103f0 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
10400 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
10410 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
10420 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
10430 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
10440 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
10450 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
10460 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
10470 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
10480 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10490 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
104a0 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
104b0 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
104c0 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
104d0 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
104e0 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
104f0 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
10500 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
10510 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
10520 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
10530 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
10540 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
10550 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10560 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
10570 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
10580 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
10590 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
105a0 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
105b0 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
105c0 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
105d0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
105e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
105f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
10600 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10610 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10620 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
10630 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
10640 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10650 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
10660 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
10670 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
10680 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
10690 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
106a0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
106b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
106c0 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
106d0 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
106e0 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
106f0 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10700 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10710 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
10720 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
10730 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
10740 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10750 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
10760 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10770 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
10780 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
10790 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
107a0 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
107b0 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
107c0 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
107d0 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
107e0 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
107f0 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
10800 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
10810 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
10820 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
10830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10840 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
10850 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10860 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10870 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
10880 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
10890 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
108a0 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
108b0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
108c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
108d0 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
108e0 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
108f0 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10900 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10910 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10920 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10930 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10940 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10950 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10960 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10970 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10980 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10990 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
109a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
109b0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
109c0 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
109d0 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
109e0 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
109f0 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10a00 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10a10 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10a20 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10a30 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10a40 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10a50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10a60 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10a70 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10a80 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10a90 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10aa0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10ab0 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10ac0 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10ad0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10ae0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10af0 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10b00 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10b10 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b20 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10b30 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10b40 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10b50 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10b60 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10b70 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10b80 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10b90 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10ba0 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10bb0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10bc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10bd0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10be0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10bf0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10c00 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10c10 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10c20 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10c40 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10c50 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10c60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10c70 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10c80 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10c90 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10ca0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10cb0 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10cc0 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10cd0 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10ce0 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10cf0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10d00 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10d10 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10d20 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10d30 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10d40 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10d50 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10d60 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10d70 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10d80 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10d90 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10da0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10db0 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10dc0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10dd0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10de0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10df0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10e00 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10e10 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10e20 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10e30 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10e40 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10e50 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10e60 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10e70 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10e80 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10e90 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
10ea0 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
10eb0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
10ec0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
10ed0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
10ee0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10ef0 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
10f00 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
10f10 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
10f20 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
10f30 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
10f40 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
10f50 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
10f60 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10f70 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
10f80 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
10f90 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
10fa0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
10fb0 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
10fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10fd0 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
10fe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ff0 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
11000 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
11010 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
11020 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
11030 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
11040 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
11050 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
11060 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
11070 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
11080 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
11090 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
110a0 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
110b0 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
110c0 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
110d0 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
110e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
110f0 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
11100 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
11110 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
11120 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
11130 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
11140 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11150 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
11160 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
11170 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11180 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
11190 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
111a0 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
111b0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
111c0 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
111d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
111e0 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
111f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11200 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
11210 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
11220 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
11230 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
11240 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
11250 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
11260 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
11270 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
11280 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
11290 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
112a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
112b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
112c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
112d0 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
112e0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
112f0 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
11300 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11310 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11320 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
11330 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
11340 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
11350 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
11360 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
11390 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
113a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
113b0 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
113c0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
113d0 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
113e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
113f0 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
11400 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
11410 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
11420 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11430 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11440 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11450 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
11460 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
11470 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
11480 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11490 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
114a0 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
114b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
114c0 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
114d0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
114e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
114f0 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
11500 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
11510 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
11520 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
11530 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
11540 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
11550 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
11560 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11570 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11580 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
11590 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
115a0 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
115b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
115c0 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
115d0 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
115e0 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
115f0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
11600 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
11610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
11620 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
11630 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
11640 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
11650 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
11660 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
11670 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
11680 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
11690 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
116a0 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
116b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
116c0 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
116d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
116e0 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
116f0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
11700 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
11710 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
11720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11730 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11740 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11750 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11760 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
11770 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
11780 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11790 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
117a0 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
117b0 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
117c0 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
117d0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
117e0 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
117f0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
11800 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
11810 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
11820 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
11830 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
11840 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11850 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11860 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11870 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
11880 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
11890 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
118a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
118b0 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
118c0 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
118d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
118e0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
118f0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11900 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11910 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11920 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11930 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11940 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11950 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11960 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11980 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11990 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
119a0 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
119b0 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
119c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
119d0 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
119e0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
119f0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11a00 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11a10 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11a20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11a30 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11a40 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11a50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11a60 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11a70 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11a80 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11a90 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11aa0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11ab0 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11ac0 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11ad0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11ae0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11af0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11b00 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11b10 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11b20 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11b30 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11b40 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11b50 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11b60 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11b70 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11b80 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11b90 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11ba0 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11bb0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11bc0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11bd0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11be0 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11bf0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11c00 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11c10 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11c20 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11c30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11c40 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11c50 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11c60 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11c70 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11c80 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11c90 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11ca0 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11cb0 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11cc0 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11cd0 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11ce0 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11cf0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11d00 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11d10 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11d20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11d30 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11d40 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11d50 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11d60 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11d70 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11d80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11d90 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11da0 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11dc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11dd0 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11de0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11df0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11e00 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11e10 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11e20 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11e30 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11e40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11e50 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11e60 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11e70 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11e80 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11e90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11ea0 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
11eb0 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
11ec0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
11ed0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11ee0 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
11ef0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
11f00 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
11f10 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
11f20 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
11f30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
11f40 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11f50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11f60 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
11f70 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11f80 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
11f90 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
11fa0 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
11fb0 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
11fc0 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
11fd0 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
11fe0 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
11ff0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
12000 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
12010 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
12020 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
12030 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
12040 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
12050 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
12060 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
12070 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
12080 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
12090 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
120a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
120b0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
120c0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
120d0 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
120e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
120f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
12100 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
12110 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
12120 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
12130 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
12140 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
12150 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12160 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
12170 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
12180 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
12190 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
121a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
121b0 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
121c0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
121d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
121e0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
121f0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12200 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
12210 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
12220 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
12230 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
12240 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
12250 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
12260 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
12270 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
12290 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
122a0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
122b0 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
122c0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
122d0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
122e0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
122f0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
12300 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
12310 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
12320 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
12330 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12340 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12350 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
12360 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12370 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
12380 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
12390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
123a0 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
123b0 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
123c0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
123d0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
123e0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
123f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12400 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
12410 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
12420 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
12430 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
12440 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
12450 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12460 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
12470 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
12480 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
12490 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
124a0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
124b0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
124c0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
124d0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
124e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
124f0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
12500 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
12510 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
12520 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
12530 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
12540 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
12550 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
12560 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
12570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12580 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
12590 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
125a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
125b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
125c0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
125d0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
125e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
125f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
12600 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
12610 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
12620 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
12630 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
12640 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
12650 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
12660 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12670 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
12680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
12690 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
126a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
126b0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
126c0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
126d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
126e0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
126f0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
12700 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
12710 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
12720 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
12730 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12740 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
12750 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
12760 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
12770 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
12780 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12790 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
127a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
127b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
127c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
127d0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
127e0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
127f0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
12800 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12810 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
12820 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
12830 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
12840 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
12850 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
12860 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
12870 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
12880 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
12890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
128a0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
128b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
128c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
128d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
128e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
128f0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
12900 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
12910 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12920 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
12930 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
12940 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12950 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12960 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12980 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
12990 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
129a0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
129b0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
129c0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
129d0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
129e0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
129f0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
12a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
12a10 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
12a20 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
12a30 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
12a40 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
12a50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12a60 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12a70 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12a80 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
12a90 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
12aa0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
12ab0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12ac0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
12ad0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
12ae0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
12af0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12b00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12b10 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
12b20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
12b30 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
12b40 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12b50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12b60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12b70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12b80 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
12b90 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
12ba0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12bb0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
12bc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
12bd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
12be0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
12bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12c00 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
12c10 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
12c20 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12c30 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
12c40 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12c50 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12c60 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12c70 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12c80 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12c90 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12ca0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12cb0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12cc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
12cd0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
12ce0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
12cf0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
12d00 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
12d10 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
12d20 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
12d30 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
12d40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12d50 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12d60 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12d70 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12d80 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12d90 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12da0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12db0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
12dc0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
12dd0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
12de0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
12df0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
12e00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12e10 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
12e20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
12e30 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
12e40 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
12e50 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12e60 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
12e70 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12e80 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
12e90 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
12ea0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
12eb0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
12ec0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
12ed0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
12ee0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
12ef0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
12f00 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
12f10 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
12f20 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
12f30 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
12f40 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
12f50 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
12f60 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
12f70 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
12f80 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12f90 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
12fa0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12fb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12fc0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
12fd0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
12fe0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
12ff0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
13000 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
13010 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
13020 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
13030 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
13040 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
13050 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
13060 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
13070 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
13080 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
13090 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
130a0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
130b0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
130c0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
130d0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
130e0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
130f0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
13100 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
13110 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
13120 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
13130 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
13140 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
13150 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
13160 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
13170 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
13180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13190 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
131a0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
131b0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
131c0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
131d0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
131e0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
131f0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
13200 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
13210 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
13220 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
13230 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13240 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
13250 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
13260 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
13270 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
13280 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
13290 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
132a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132c0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
132d0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
132e0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
132f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13300 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
13310 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
13320 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
13330 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
13340 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
13350 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
13360 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
13370 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
13380 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
13390 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
133a0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
133b0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
133c0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
133d0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
133e0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
133f0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
13400 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
13410 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13420 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
13430 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
13440 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
13450 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
13460 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
13470 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
13480 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
13490 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
134a0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
134b0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
134c0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
134d0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
134e0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
134f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13500 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
13510 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
13520 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
13530 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
13540 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
13550 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
13560 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
13570 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
13580 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
13590 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
135a0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
135b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
135c0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
135d0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
135e0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
135f0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
13600 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
13610 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
13620 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
13630 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13640 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
13650 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
13660 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
13670 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
13680 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
13690 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
136a0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
136b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
136c0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
136d0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
136e0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
136f0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
13700 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
13710 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
13720 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
13730 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13740 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
13750 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
13760 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13770 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
13780 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
13790 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
137a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
137b0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
137c0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
137d0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
137e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
137f0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
13800 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
13810 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
13820 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13830 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
13840 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13850 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
13860 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
13870 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13880 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
13890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
138a0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
138b0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
138c0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
138d0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
138e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
138f0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13900 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13910 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13920 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13930 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13940 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13950 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13960 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13970 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13980 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
13990 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
139a0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
139b0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
139c0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
139d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
139e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
139f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
13a00 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13a10 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13a20 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13a30 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13a40 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13a50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13a60 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13a70 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13a80 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13a90 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13aa0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13ab0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13ac0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
13ad0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13af0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13b00 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13b10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13b20 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13b30 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13b50 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13b60 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13b70 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13b80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13b90 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
13ba0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
13bb0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13bc0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
13bd0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
13be0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13bf0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
13c00 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
13c10 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13c20 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13c30 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13c40 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13c50 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13c60 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13c70 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13c80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13c90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13ca0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13cb0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
13cc0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13cd0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13ce0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
13cf0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
13d00 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
13d10 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13d20 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13d30 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13d40 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13d50 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13d60 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13d70 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13d80 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13d90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13da0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13db0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
13dc0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
13dd0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
13de0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
13df0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
13e00 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
13e10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13e20 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
13e30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13e40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13e60 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13e70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e80 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13e90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13ea0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
13eb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ec0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
13ed0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13ee0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13ef0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13f00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13f10 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13f20 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
13f30 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
13f40 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13f50 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13f60 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13f80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13f90 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
13fa0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13fb0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
13fc0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
13fd0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
13fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ff0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
14000 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
14010 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
14020 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
14030 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
14040 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
14050 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
14060 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
14070 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
14080 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
14090 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
140a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
140b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
140c0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
140d0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
140e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
140f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14100 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14110 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14120 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14130 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
14140 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
14150 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
14160 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
14170 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
14180 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14190 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
141a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
141b0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
141c0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
141d0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
141e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
141f0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
14200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14210 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
14220 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14230 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
14240 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14250 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14260 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14270 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
14280 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
14290 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
142a0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
142b0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
142c0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
142d0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
142e0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
142f0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
14300 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14310 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
14320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14330 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
14340 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
14350 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
14360 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
14370 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
14380 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14390 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
143a0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
143b0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
143c0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
143d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
143e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
143f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
14400 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
14410 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
14420 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
14430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14440 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
14450 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
14460 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
14470 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
14480 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14490 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
144a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
144b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
144c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
144d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
144e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
144f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
14500 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
14510 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
14520 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
14530 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
14540 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
14560 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14570 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
14580 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14590 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
145a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
145b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
145d0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
145e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
145f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14600 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14610 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14620 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14630 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14640 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14650 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14660 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14670 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14680 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
14690 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
146a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
146b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
146c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
146d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
146e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
146f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14700 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14710 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
14720 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
14730 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
14740 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
14750 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14770 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
14780 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
14790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
147a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
147b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
147c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
147d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
147e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
147f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14800 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14810 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
14820 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14830 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14840 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14850 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14860 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14870 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14880 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
14890 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
148a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
148b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
148c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
148d0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
148e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
148f0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
14900 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
14910 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14920 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14930 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14940 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14950 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14960 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14970 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14980 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14990 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
149a0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
149b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
149c0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  SMALL_MALLOC]] <
149d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
149e0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64  _SMALL_MALLOC</d
149f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14a10 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  ALL_MALLOC optio
14a20 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14a30 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79  rgument of.** ty
14a40 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
14a50 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14a60 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20  , which if true 
14a70 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20  provides a hint 
14a80 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61  to.** SQLite tha
14a90 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69  t it should avoi
14aa0 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  d large memory a
14ab0 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f  llocations if po
14ac0 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74  ssible..** SQLit
14ad0 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65  e will run faste
14ae0 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20  r if it is free 
14af0 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65  to make large me
14b00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14b10 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70  ,.** but some ap
14b20 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
14b30 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c  prefer to run sl
14b40 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65  ower in exchange
14b50 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65   for.** guarante
14b60 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20  es about memory 
14b70 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68  fragmentation th
14b80 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20  at are possible 
14b90 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f  if large.** allo
14ba0 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69  cations are avoi
14bb0 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ded.  This hint 
14bc0 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e  is normally off.
14bd0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14be0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14bf0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
14c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14c10 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
14c20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14c30 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14c40 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14c50 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14c60 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14c70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14c80 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14c90 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14ca0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14cb0 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
14cc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14cd0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14ce0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14cf0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
14d00 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
14d10 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
14d20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
14d30 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
14d40 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14d50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14d60 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14d70 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14d80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14d90 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14da0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14db0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
14dc0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14dd0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
14de0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
14df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14e00 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
14e10 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
14e20 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
14e30 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
14e40 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14e50 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14e60 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14e70 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14e80 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14e90 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14ea0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14ec0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
14ed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14ee0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
14ef0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14f10 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  H option is no l
14f20 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c  onger used..** <
14f30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14f50 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14f60 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14f70 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14f80 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14f90 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
14fa0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14fb0 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
14fc0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
14fd0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
14fe0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
14ff0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
15000 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
15010 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
15020 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
15030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
15040 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
15050 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15060 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
15080 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
15090 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
150a0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
150b0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
150c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
150d0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
150e0 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
150f0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
15100 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
15110 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
15120 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
15130 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
15140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
15150 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
15160 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
15170 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
15180 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
15190 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
151a0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
151b0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
151c0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
151d0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
151e0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
151f0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
15200 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15210 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15220 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15230 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15240 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
15250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15260 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
15270 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
15280 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
15290 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
152a0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
152b0 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
152c0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
152d0 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
152e0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
152f0 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
15300 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
15310 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
15320 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
15330 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
15340 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
15350 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
15360 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
15370 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
15380 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
15390 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
153a0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
153b0 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
153c0 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
153d0 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
153e0 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
153f0 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
15400 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
15410 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
15420 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
15430 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
15440 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
15450 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
15460 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
15470 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
15480 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
15490 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
154a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
154b0 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
154c0 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
154d0 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
154e0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
154f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15500 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
15510 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
15520 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
15530 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
15540 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
15550 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
15560 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
15570 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
15580 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
15590 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
155a0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
155b0 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
155c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
155d0 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
155e0 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
155f0 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
15600 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
15610 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
15620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15630 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15660 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15670 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
15680 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15690 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
156a0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
156b0 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
156c0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
156d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
156e0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
156f0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
15700 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
15710 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
15720 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
15730 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
15740 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15750 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
15760 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
15770 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
15780 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
15790 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
157a0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
157b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
157c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
157d0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
157e0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
157f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
15800 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15810 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
15820 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
15830 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
15840 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
15850 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
15860 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
15870 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
15880 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
15890 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
158a0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
158b0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
158c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
158d0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
158e0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
158f0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
15900 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
15910 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
15920 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
15930 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
15940 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15960 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15970 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
15980 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
15990 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
159a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
159b0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
159c0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
159d0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
159e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
159f0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
15a00 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15a10 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
15a20 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
15a30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
15a40 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
15a50 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
15a60 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
15a70 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
15a80 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15a90 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
15aa0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
15ab0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
15ac0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
15ad0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15ae0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
15af0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
15b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b10 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
15b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15b30 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15b40 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15b50 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
15b60 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15b70 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15b80 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
15b90 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
15ba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15bb0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15bc0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
15bd0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15be0 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
15bf0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
15c00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
15c10 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
15c20 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
15c30 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
15c40 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
15c50 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
15c60 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
15c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15c80 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15c90 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
15ca0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
15cb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15cc0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
15cd0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15ce0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15cf0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15d00 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15d10 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15d20 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15d30 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15d40 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15d50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15d60 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15d70 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15d90 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15dc0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
15dd0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15de0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
15df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
15e00 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
15e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15e20 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
15e30 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15e40 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
15e50 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15e70 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15e80 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15e90 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15eb0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15ec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
15ed0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
15ee0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
15ef0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
15f00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
15f10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
15f20 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15f40 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15f50 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
15f60 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
15f70 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15f80 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15f90 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15fa0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15fb0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
15fc0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
15fd0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
16040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
16050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
16060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
16070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
16080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
16090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
160a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
160b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
160c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
160d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
160e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
160f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16100 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16110 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
16120 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16130 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
16140 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16150 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
16160 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
16170 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
16180 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
16190 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
161a0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
161b0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
161c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
161d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
161e0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
161f0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16200 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16210 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
16220 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16230 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
16240 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
16250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16260 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
16270 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
16280 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
16290 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
162a0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
162b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
162c0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
162d0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
162e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
162f0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
16300 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16310 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16320 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
16330 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
16340 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16360 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
16370 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
16380 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16390 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
163a0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
163b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
163c0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
163d0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
163e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
163f0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16400 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
16410 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
16420 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
16430 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
16440 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16450 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
16460 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
16470 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
16480 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
16490 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
164a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
164b0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
164c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
164d0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
164e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
164f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16500 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
16510 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16520 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
16530 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16540 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16550 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16560 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
16570 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
16580 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
16590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
165a0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
165b0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
165c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
165d0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
165e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
165f0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
16600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16610 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16620 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
16630 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
16640 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
16650 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
16660 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
16670 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16680 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
16690 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
166a0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
166b0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
166c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
166d0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
166e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
166f0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
16700 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16710 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
16720 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
16730 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
16740 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
16750 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
16760 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
16770 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
16780 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
16790 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
167a0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
167b0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
167c0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
167d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
167e0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
167f0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
16800 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
16810 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16820 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
16830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16840 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16850 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
16860 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
16870 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
16880 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
16890 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
168a0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
168b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
168c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
168d0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
168e0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
168f0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
16900 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
16910 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
16920 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16930 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
16940 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16950 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16960 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16970 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
16980 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
16990 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
169a0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
169b0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
169c0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
169d0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
169e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
169f0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
16a00 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16a10 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
16a20 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
16a30 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
16a40 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
16a50 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16a60 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16a70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
16a80 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
16a90 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16ab0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16ac0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
16ad0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16ae0 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
16af0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16b00 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
16b10 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
16b20 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
16b30 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16b40 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
16b50 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
16b60 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
16b70 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16b80 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
16b90 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
16ba0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16bb0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
16bc0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
16bd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16be0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
16bf0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
16c00 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
16c10 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
16c20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
16c30 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
16c40 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16c50 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
16c60 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
16c70 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
16c80 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
16c90 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16ca0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
16cb0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16cc0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
16cd0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
16ce0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
16cf0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
16d00 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
16d10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
16d20 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
16d30 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
16d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16d50 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
16d60 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
16d70 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16d80 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
16d90 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
16da0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
16db0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
16dc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
16dd0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
16de0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
16df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
16e00 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16e10 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
16e20 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16e30 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
16e40 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16e50 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16e60 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
16e70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
16e80 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
16e90 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
16ea0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
16eb0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
16ec0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16ed0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
16ee0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
16ef0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
16f00 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
16f10 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
16f20 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16f30 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
16f40 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
16f50 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
16f60 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16f80 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
16f90 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
16fa0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16fb0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
16fc0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
16fd0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
16fe0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16ff0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
17000 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
17010 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
17020 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
17030 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
17040 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
17050 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
17060 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
17070 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
17080 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
17090 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
170a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
170b0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
170c0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
170d0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
170e0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
170f0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
17100 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
17110 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
17120 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17130 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
17140 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
17150 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17160 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
17170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17180 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
17190 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
171a0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
171b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
171c0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
171d0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
171e0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
171f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
17200 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
17210 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
17220 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17230 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
17240 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17250 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
17260 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
17270 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
17280 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
17290 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
172a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
172b0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
172c0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
172d0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
172e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
172f0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
17300 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
17310 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
17320 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
17330 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
17340 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
17350 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
17360 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
17370 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
17380 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
17390 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
173a0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
173b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
173c0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
173d0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
173e0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
173f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17400 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
17410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17420 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
17430 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17440 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
17450 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
17460 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17470 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
17480 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
17490 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
174a0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
174b0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
174c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
174d0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
174e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
174f0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
17500 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
17510 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
17520 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
17530 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
17540 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
17550 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
17560 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
17570 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17580 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
17590 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
175a0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
175b0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
175c0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
175d0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
175e0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
175f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17600 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
17610 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
17620 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
17630 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
17640 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
17650 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
17660 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17670 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
17680 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17690 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
176a0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
176b0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
176c0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
176d0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
176e0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
176f0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
17700 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
17710 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
17720 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
17730 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
17740 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
17750 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
17760 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
17770 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
17780 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
17790 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
177a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
177b0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
177c0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
177d0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
177e0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
177f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17800 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
17810 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
17820 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
17830 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
17840 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
17850 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
17860 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
17870 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
17880 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
17890 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
178a0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
178b0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
178c0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
178d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
178e0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
178f0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
17900 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
17910 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17920 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
17930 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
17940 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17950 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17970 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
17980 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17990 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
179a0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
179b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
179c0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
179d0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
179e0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
179f0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
17a00 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
17a10 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
17a20 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
17a30 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
17a40 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
17a50 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17a60 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
17a70 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
17a80 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
17a90 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
17aa0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
17ab0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
17ac0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
17ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17ae0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
17af0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17b00 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
17b10 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17b20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17b30 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
17b40 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17b50 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17b60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17b70 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
17b80 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
17b90 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
17ba0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
17bb0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
17bc0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
17bd0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
17be0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
17bf0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
17c00 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
17c10 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
17c20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
17c30 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
17c40 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
17c50 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
17c60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17c70 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
17c80 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17c90 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
17ca0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17cb0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
17cc0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17cd0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17ce0 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
17cf0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
17d00 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
17d10 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
17d20 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
17d30 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
17d40 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
17d50 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
17d60 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
17d70 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17d80 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
17d90 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
17da0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
17db0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
17dc0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
17dd0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
17de0 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
17df0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
17e00 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
17e10 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
17e20 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
17e30 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
17e40 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
17e50 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
17e60 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
17e70 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
17e80 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
17e90 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
17ea0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
17eb0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
17ec0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17ed0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
17ee0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17ef0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17f00 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
17f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17f20 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
17f30 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17f40 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17f50 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
17f60 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
17f70 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
17f80 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
17f90 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
17fa0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
17fb0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
17fc0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
17fd0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
17fe0 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
17ff0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
18000 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
18010 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
18020 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
18030 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
18040 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
18050 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
18060 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
18070 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
18080 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
18090 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
180a0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
180b0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
180c0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
180d0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
180e0 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
180f0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
18100 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
18110 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
18120 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
18130 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
18140 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
18150 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
18160 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
18170 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
18180 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
18190 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
181a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
181b0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
181c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
181d0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
181e0 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  REF_SIZE.** <dd>
181f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18200 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
18210 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20   option accepts 
18220 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
18230 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69  er.** of type (i
18240 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61  nt) - the new va
18250 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65  lue of the sorte
18260 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65  r-reference size
18270 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55   threshold..** U
18280 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c  sually, when SQL
18290 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65  ite uses an exte
182a0 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64  rnal sort to ord
182b0 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72  er records accor
182c0 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52  ding.** to an OR
182d0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61  DER BY clause, a
182e0 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72  ll fields requir
182f0 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
18300 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20   are present in 
18310 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65  the.** sorted re
18320 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20  cords. However, 
18330 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  if SQLite determ
18340 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68  ines based on th
18350 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a  e declared type.
18360 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f  ** of a table co
18370 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61  lumn that its va
18380 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  lues are likely 
18390 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65  to be very large
183a0 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61   - larger.** tha
183b0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64  n the configured
183c0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
183d0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
183e0 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65   - then a refere
183f0 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64  nce.** is stored
18400 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20   in each sorted 
18410 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72  record and the r
18420 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76  equired column v
18430 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20  alues loaded.** 
18440 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
18450 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65  e as records are
18460 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72   returned in sor
18470 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64  ted order. The d
18480 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
18490 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
184a0 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20  is to never use 
184b0 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
184c0 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20  n. Specifying a 
184d0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c  .** negative val
184e0 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69  ue for this opti
184f0 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20  on restores the 
18500 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75  default behaviou
18510 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  r..** This optio
18520 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
18530 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
18540 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
18550 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
18560 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45  ABLE_SORTER_REFE
18570 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d  RENCES] compile-
18580 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  time option..**.
18590 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
185a0 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
185b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
185c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41  _CONFIG_MEMDB_MA
185d0 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  XSIZE.** <dd>The
185e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
185f0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70 74  EMDB_MAXSIZE opt
18600 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69  ion accepts a si
18610 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ngle parameter.*
18620 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  * [sqlite3_int64
18630 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  ] parameter whic
18640 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
18650 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66 6f   maximum size fo
18660 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a  r an in-memory.*
18670 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  * database creat
18680 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18690 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d  3_deserialize()]
186a0 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74 20  .  This default 
186b0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20  maximum.** size 
186c0 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64 20  can be adjusted 
186d0 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20 69  up or down for i
186e0 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62 61  ndividual databa
186f0 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ses using the.**
18700 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
18710 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c 69  IZE_LIMIT] [sqli
18720 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
18730 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20  |file-control]. 
18740 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66   If this.** conf
18750 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69 6e  iguration settin
18760 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 2c  g is never used,
18770 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
18780 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65 74  t maximum is det
18790 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
187a0 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42 5f  e [SQLITE_MEMDB_
187b0 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45 5d  DEFAULT_MAXSIZE]
187c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
187d0 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a 2a  tion.  If that.*
187e0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
187f0 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65 74  ption is not set
18800 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
18810 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31 30  lt maximum is 10
18820 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64  73741824..** </d
18830 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18850 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18860 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
18880 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
18890 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
188a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
188b0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
188c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
188d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
188e0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
188f0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18900 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18910 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18920 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18930 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18940 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18950 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18960 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
18970 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72   6  /* No longer
18980 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
18990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
189a0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
189b0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
189c0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
189d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
189e0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
189f0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18a00 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
18a10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
18a30 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
18a40 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
18a60 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
18a70 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
18a80 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18a90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18aa0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
18ab0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
18ac0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
18ad0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
18ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
18af0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
18b00 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
18b10 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
18b20 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
18b30 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
18b40 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18b50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18b60 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
18b70 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
18b80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18b90 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
18ba0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
18bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18bc0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
18bd0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
18be0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18c00 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
18c10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18c30 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
18c40 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18c50 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c70 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
18c80 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
18c90 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
18ca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18cb0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
18cc0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
18cd0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18ce0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18cf0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
18d00 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
18d10 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
18d30 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
18d40 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
18d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d70 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
18d80 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
18d90 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
18da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18db0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
18dc0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
18dd0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
18de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18df0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
18e00 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
18e10 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
18e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e30 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18e40 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
18e50 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
18e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e70 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
18e80 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20  LLOC        27  
18e90 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
18ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18eb0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
18ec0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69  ZE      28  /* i
18ed0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18ee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18ef0 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20  G_MEMDB_MAXSIZE 
18f00 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71 6c        29  /* sql
18f10 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f  ite3_int64 */../
18f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
18f30 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
18f40 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
18f50 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
18f60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
18f70 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
18f80 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
18f90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
18fa0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
18fb0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
18fc0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
18fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
18fe0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
18ff0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
19000 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
19010 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
19020 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
19030 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
19040 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
19050 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19060 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
19070 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
19080 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
19090 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
190a0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
190b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
190c0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
190d0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
190e0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
190f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
19100 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
19110 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
19120 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
19130 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
19140 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
19150 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
19160 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
19170 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
19180 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
19190 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
191a0 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  DE]].** <dt>SQLI
191b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
191c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
191d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
191e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
191f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19200 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
19210 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
19220 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
19230 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
19240 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
19250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19260 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
19270 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
19280 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
19290 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
192a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
192b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
192c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
192d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
192e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
192f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
19300 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
19310 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19320 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
19330 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
19340 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
19350 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
19360 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
19370 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
19380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19390 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
193a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
193b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
193c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
193d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
193e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
193f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
19400 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
19410 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
19420 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
19430 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
19440 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
19450 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
19460 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
19470 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
19480 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
19490 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
194a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
194b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
194c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
194d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
194e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
194f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
19500 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
19510 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
19520 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
19530 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
19540 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
19550 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
19560 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
19570 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
19580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19590 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
195a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
195b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
195c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
195d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
195e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
195f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
19600 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
19610 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
19620 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
19630 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
19640 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
19650 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
19660 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
19670 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
19680 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19690 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
196a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
196b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
196c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
196d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
196e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
196f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
19700 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
19710 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
19720 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d  FIG_ENABLE_FKEY]
19730 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
19740 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19750 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
19760 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19770 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19780 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
19790 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
197a0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
197b0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
197c0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
197d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
197e0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
197f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19800 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19810 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19820 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19830 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
19840 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
19850 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
19860 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
19870 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
19880 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
19890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
198a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
198b0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
198c0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
198d0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
198e0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
198f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
19900 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
19910 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19920 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
19930 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
19940 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19950 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
19960 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
19970 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
19980 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
19990 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
199a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
199b0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a  NABLE_TRIGGER]].
199c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
199d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
199e0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
199f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19a00 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
19a10 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
19a20 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
19a30 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
19a40 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19a50 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19a60 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19a80 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19a90 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19aa0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
19ab0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19ac0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
19ad0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19ae0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
19af0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
19b00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19b10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19b20 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19b30 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19b40 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19b50 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
19b60 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
19b70 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
19b80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
19b90 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
19ba0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
19bb0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19bc0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19bd0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
19be0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19bf0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19c00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
19c10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c20 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19c30 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  R]].** <dt>SQLIT
19c40 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19c50 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19c60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19c70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19c80 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19c90 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 5b  disable the.** [
19ca0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19cb0 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68  ] function which
19cc0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
19cd0 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74  ** [FTS3] full-t
19ce0 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e  ext search engin
19cf0 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20  e extension..** 
19d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
19d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
19d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
19d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
19d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
19d60 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
19d70 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74  er() or.** posit
19d80 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74  ive to enable ft
19d90 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
19da0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
19db0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
19dc0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ** unchanged..**
19dd0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19de0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19df0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19e00 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
19e10 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19e20 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19e30 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69  ther fts3_tokeni
19e40 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
19e50 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19e60 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19e70 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19e80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19e90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19ea0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19eb0 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
19ec0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
19ed0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
19ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19ef0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19f00 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a 20  _EXTENSION]].** 
19f10 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19f20 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
19f30 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
19f40 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19f50 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19f60 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
19f70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
19f80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
19f90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
19fa0 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
19fb0 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
19fc0 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
19fd0 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
19fe0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
19ff0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
1a000 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1a010 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
1a020 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
1a030 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a040 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
1a050 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
1a060 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
1a070 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
1a080 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
1a090 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
1a0a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a0b0 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
1a0c0 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
1a0d0 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
1a0e0 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
1a0f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1a100 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
1a110 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
1a120 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a130 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1a140 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
1a150 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
1a160 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
1a170 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
1a180 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
1a190 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
1a1a0 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
1a1b0 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
1a1c0 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
1a1d0 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
1a1e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
1a1f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a200 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a210 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a220 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a230 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a240 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a250 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
1a260 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
1a270 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
1a280 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
1a290 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1a2a0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
1a2b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
1a2c0 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
1a2d0 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
1a2e0 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
1a2f0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
1a300 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
1a310 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1a320 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
1a330 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  NAME]] <dt>SQLIT
1a340 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a350 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
1a360 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a370 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
1a380 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
1a390 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
1a3a0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
1a3b0 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
1a3c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a3d0 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
1a3e0 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
1a3f0 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
1a400 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
1a410 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
1a420 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
1a430 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
1a440 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
1a450 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
1a460 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
1a470 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
1a480 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
1a490 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
1a4a0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
1a4b0 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
1a4c0 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
1a4d0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
1a4e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a4f0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
1a500 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1a510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1a520 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 0a  KPT_ON_CLOSE]] .
1a530 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a540 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
1a550 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  N_CLOSE</dt>.** 
1a560 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68  <dd> Usually, wh
1a570 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e  en a database in
1a580 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f   wal mode is clo
1a590 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20  sed or detached 
1a5a0 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62  from a .** datab
1a5b0 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69  ase handle, SQLi
1a5c0 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69  te checks if thi
1a5d0 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74  s will mean that
1a5e0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e   there are now n
1a5f0 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  o .** connection
1a600 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20  s at all to the 
1a610 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c  database. If so,
1a620 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63   it performs a c
1a630 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70  heckpoint .** op
1a640 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63  eration before c
1a650 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65  losing the conne
1a660 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69  ction. This opti
1a670 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  on may be used t
1a680 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68  o.** override th
1a690 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68  is behaviour. Th
1a6a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a6b0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
1a6c0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73   operation.** is
1a6d0 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f   an integer - po
1a6e0 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c  sitive to disabl
1a6f0 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  e checkpoints-on
1a700 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20  -close, or zero 
1a710 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29  (the.** default)
1a720 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c   to enable them,
1a730 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f   and negative to
1a740 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1a750 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
1a760 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a770 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a780 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a790 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69  .** into which i
1a7a0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a7b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a7c0 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  ther checkpoints
1a7d0 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76  -on-close.** hav
1a7e0 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  e been disabled 
1a7f0 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20  - 0 if they are 
1a800 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
1a810 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20  if they are..** 
1a820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a830 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a840 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74 3e  ABLE_QPSG]] <dt>
1a850 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a860 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e  ENABLE_QPSG</dt>
1a870 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
1a880 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a890 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e  ABLE_QPSG option
1a8a0 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
1a8b0 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65  activates.** the
1a8c0 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20   [query planner 
1a8d0 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e  stability guaran
1a8e0 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68  tee] (QPSG).  Wh
1a8f0 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61  en the QPSG is a
1a900 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67  ctive,.** a sing
1a910 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61  le SQL query sta
1a920 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61  tement will alwa
1a930 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  ys use the same 
1a940 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64  algorithm regard
1a950 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65  less.** of value
1a960 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  s of [bound para
1a970 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51  meters].)^ The Q
1a980 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d  PSG disables som
1a990 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61  e query optimiza
1a9a0 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f  tions.** that lo
1a9b0 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73  ok at the values
1a9c0 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65   of bound parame
1a9d0 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20  ters, which can 
1a9e0 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65  make some querie
1a9f0 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75  s.** slower.  Bu
1aa00 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74  t the QPSG has t
1aa10 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20  he advantage of 
1aa20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65  more predictable
1aa30 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68   behavior.  With
1aa40 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74  .** the QPSG act
1aa50 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ive, SQLite will
1aa60 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
1aa70 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20  same query plan 
1aa80 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a  in the field as.
1aa90 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69  ** was used duri
1aaa0 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68  ng testing in th
1aab0 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69  e lab..** The fi
1aac0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1aad0 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
1aae0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
1aaf0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
1ab00 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70   .** the QPSG, p
1ab10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1ab20 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74  e QPSG, or negat
1ab30 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1ab40 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
1ab50 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e  anged. The secon
1ab60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1ab70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1ab80 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1ab90 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
1aba0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1abb0 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51  te whether the Q
1abc0 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20  PSG is disabled 
1abd0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
1abe0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1abf0 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l..** </dd>.**.*
1ac00 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1ac10 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 5d  FIG_TRIGGER_EQP]
1ac20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1ac30 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1ac40 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42  P</dt>.** <dd> B
1ac50 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f  y default, the o
1ac60 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e  utput of EXPLAIN
1ac70 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d   QUERY PLAN comm
1ac80 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a  ands does not .*
1ac90 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74  * include output
1aca0 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69   for any operati
1acb0 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ons performed by
1acc0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1acd0 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f  s. This.** optio
1ace0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  n is used to set
1acf0 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64   or clear (the d
1ad00 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74  efault) a flag t
1ad10 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73  hat governs this
1ad20 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68  .** behavior. Th
1ad30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ad40 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
1ad50 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1ad60 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f   integer -.** po
1ad70 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1ad80 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67   output for trig
1ad90 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72  ger programs, or
1ada0 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65   zero to disable
1adb0 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74   it,.** or negat
1adc0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1add0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1ade0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1adf0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1ae00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1ae10 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1ae20 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a  h is written .**
1ae30 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1ae40 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70  ate whether outp
1ae50 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20  ut-for-triggers 
1ae60 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65  has been disable
1ae70 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20  d - 0 if .** it 
1ae80 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c  is not disabled,
1ae90 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a   1 if it is.  .*
1aea0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1aeb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1aec0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d 5d  RESET_DATABASE]]
1aed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1aee0 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1aef0 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ASE</dt>.** <dd>
1af00 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f   Set the SQLITE_
1af10 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1af20 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64  ATABASE flag and
1af30 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41   then run.** [VA
1af40 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74  CUUM] in order t
1af50 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62 61  o reset a databa
1af60 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d  se back to an em
1af70 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pty database.** 
1af80 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61  with no schema a
1af90 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54  nd no content. T
1afa0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
1afb0 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20  cess works even 
1afc0 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63  for.** a badly c
1afd0 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61 73  orrupted databas
1afe0 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a  e file:.** <ol>.
1aff0 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 64  ** <li> If the d
1b000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b010 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 6e  on is newly open
1b020 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 74  ed, make sure it
1b030 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a 2a   has read the.**
1b040 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 73        database s
1b050 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72 69  chema by prepari
1b060 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64 69  ng then discardi
1b070 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61 67  ng some query ag
1b080 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 20  ainst the.**    
1b090 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 63    database, or c
1b0a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 74  alling sqlite3_t
1b0b0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
1b0c0 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e 67  data(), ignoring
1b0d0 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 72   any.**      err
1b0e0 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70 20  ors.  This step 
1b0f0 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 72  is only necessar
1b100 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61  y if the applica
1b110 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f 20  tion desires to 
1b120 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 65  keep.**      the
1b130 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c   database in WAL
1b140 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65 20   mode after the 
1b150 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73 20  reset if it was 
1b160 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 6f  in WAL mode befo
1b170 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 72  re.**      the r
1b180 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20  eset.  .** <li> 
1b190 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
1b1a0 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 43  g(db, SQLITE_DBC
1b1b0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1b1c0 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20  BASE, 1, 0);.** 
1b1d0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 78  <li> [sqlite3_ex
1b1e0 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 4d  ec](db, "[VACUUM
1b1f0 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  ]", 0, 0, 0);.**
1b200 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62   <li> sqlite3_db
1b210 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49  _config(db, SQLI
1b220 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b230 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20 30  T_DATABASE, 0, 0
1b240 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42  );.** </ol>.** B
1b250 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e 67  ecause resetting
1b260 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 64   a database is d
1b270 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20 69  estructive and i
1b280 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68 65  rreversible, the
1b290 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71 75  .** process requ
1b2a0 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66 20  ires the use of 
1b2b0 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50 49  this obscure API
1b2c0 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 74   and multiple st
1b2d0 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 65  eps to help.** e
1b2e0 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64 6f  nsure that it do
1b2f0 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 79  es not happen by
1b300 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a   accident..**.**
1b310 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
1b320 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20 3c  IG_DEFENSIVE]] <
1b330 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1b340 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 74  IG_DEFENSIVE</dt
1b350 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1b360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1b370 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 63  ENSIVE option ac
1b380 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
1b390 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 64  ivates the.** "d
1b3a0 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 66  efensive" flag f
1b3b0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
1b3c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20  nnection.  When 
1b3d0 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a 2a  the defensive.**
1b3e0 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 64   flag is enabled
1b3f0 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 75  , language featu
1b400 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 6f  res that allow o
1b410 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 0a  rdinary SQL to .
1b420 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20  ** deliberately 
1b430 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 61  corrupt the data
1b440 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 69  base file are di
1b450 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 73  sabled.  The dis
1b460 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 65  abled.** feature
1b470 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 72  s include but ar
1b480 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 6f  e not limited to
1b490 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
1b4a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1b4b0 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 74  The [PRAGMA writ
1b4c0 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20  able_schema=ON] 
1b4d0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c  statement..** <l
1b4e0 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68 65  i> Writes to the
1b4f0 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65 5d   [sqlite_dbpage]
1b500 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
1b510 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20 77  ** <li> Direct w
1b520 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f 77  rites to [shadow
1b530 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f 75   tables]..** </u
1b540 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l>.** </dd>.**.*
1b550 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b560 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48  FIG_WRITABLE_SCH
1b570 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EMA]] <dt>SQLITE
1b580 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42  _DBCONFIG_WRITAB
1b590 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e 0a 2a  LE_SCHEMA</dt>.*
1b5a0 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
1b5b0 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42  _DBCONFIG_WRITAB
1b5c0 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69 6f 6e  LE_SCHEMA option
1b5d0 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
1b5e0 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a  activates the.**
1b5f0 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d   "writable_schem
1b600 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20 68 61  a" flag. This ha
1b610 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
1b620 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63 61 6c  t and is logical
1b630 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a 2a 2a  ly equivalent.**
1b640 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50 52 41   to setting [PRA
1b650 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
1b660 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41 47  ema=ON] or [PRAG
1b670 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65  MA writable_sche
1b680 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65 20  ma=OFF]..** The 
1b690 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b6a0 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
1b6b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
1b6c0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
1b6d0 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69 74 61  le .** the writa
1b6e0 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f 73 69  ble_schema, posi
1b6f0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 77  tive to enable w
1b700 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20  ritable_schema, 
1b710 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 0a 2a  or negative to.*
1b720 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  * leave the sett
1b730 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 20 54  ing unchanged. T
1b740 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b750 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1b760 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   to an.** intege
1b770 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  r into which is 
1b780 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1b790 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1b7a0 65 72 20 74 68 65 20 77 72 69 74 61 62 6c 65 5f  er the writable_
1b7b0 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65 6e 61  schema.** is ena
1b7c0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
1b7d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1b7e0 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  call..** </dd>.*
1b7f0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1b800 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b810 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
1b820 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
1b830 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
1b840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b850 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
1b860 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
1b870 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
1b880 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
1b890 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1b8a0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
1b8b0 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
1b8c0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1b8d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b8e0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
1b8f0 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
1b900 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1b910 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b920 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
1b930 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
1b940 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1b950 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b960 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
1b970 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
1b980 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b9a0 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
1b9b0 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30  N_CLOSE      100
1b9c0 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  6 /* int int* */
1b9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b9e0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1b9f0 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 31  QPSG           1
1ba00 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  007 /* int int* 
1ba10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ba20 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47  E_DBCONFIG_TRIGG
1ba30 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20 20  ER_EQP          
1ba40 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74   1008 /* int int
1ba50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1ba60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1ba70 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20 20  ET_DATABASE     
1ba80 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 69     1009 /* int i
1ba90 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1baa0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1bab0 45 46 45 4e 53 49 56 45 20 20 20 20 20 20 20 20  EFENSIVE        
1bac0 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69 6e 74       1010 /* int
1bad0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1bae0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1baf0 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1bb00 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a 20 69         1011 /* i
1bb10 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1bb20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1bb30 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20 20  IG_MAX          
1bb40 20 20 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a           1011 /*
1bb50 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46 49   Largest DBCONFI
1bb60 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  G */../*.** CAPI
1bb70 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
1bb80 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
1bb90 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
1bba0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1bbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1bbc0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
1bbd0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
1bbe0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
1bbf0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
1bc00 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1bc10 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
1bc20 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
1bc30 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
1bc40 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
1bc50 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
1bc60 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
1bc70 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
1bc80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
1bc90 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1bca0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
1bcb0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1bcc0 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
1bcd0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
1bce0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1bcf0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
1bd00 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
1bd10 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
1bd20 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
1bd30 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
1bd40 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
1bd50 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
1bd60 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
1bd70 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
1bd80 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
1bd90 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
1bda0 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
1bdb0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
1bdc0 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
1bdd0 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
1bde0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
1bdf0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
1be00 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
1be10 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1be20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
1be30 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
1be40 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
1be50 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
1be60 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
1be70 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
1be80 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
1be90 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
1bea0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
1beb0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1bec0 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 6c   interface usual
1bed0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ly returns the [
1bee0 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65  rowid] of.** the
1bef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
1bf00 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1bf10 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
1bf20 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
1bf30 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
1bf40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bf50 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e 74   D. ^Inserts int
1bf60 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
1bf70 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
1bf80 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e 49  .** recorded. ^I
1bf90 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
1bfa0 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
1bfb0 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 65  owid tables have
1bfc0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 0a   ever occurred .
1bfd0 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ** on the databa
1bfe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
1bff0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
1c000 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1c010 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a  D) returns .** z
1c020 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65  ero..**.** As we
1c030 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 20  ll as being set 
1c040 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73  automatically as
1c050 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74   rows are insert
1c060 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 65  ed into database
1c070 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 20  .** tables, the 
1c080 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c090 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
1c0a0 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c 69  may be set expli
1c0b0 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c  citly by.** [sql
1c0c0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1c0d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1c0e0 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 6c  .** Some virtual
1c0f0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1c100 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52  ations may INSER
1c110 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69  T rows into rowi
1c120 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70  d tables as.** p
1c130 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e  art of committin
1c140 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
1c150 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 64  (e.g. to flush d
1c160 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 20  ata accumulated 
1c170 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20  in memory.** to 
1c180 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 63  disk). In this c
1c190 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  ase subsequent c
1c1a0 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 6e  alls to this fun
1c1b0 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 65  ction return the
1c1c0 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69   rowid.** associ
1c1d0 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 20  ated with these 
1c1e0 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 20  internal INSERT 
1c1f0 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 63  operations, whic
1c200 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75  h leads to .** u
1c210 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 6c  nintuitive resul
1c220 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c  ts. Virtual tabl
1c230 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1c240 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 20  s that do write 
1c250 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c  to rowid.** tabl
1c260 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 63  es in this way c
1c270 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 72  an avoid this pr
1c280 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 69  oblem by restori
1c290 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
1c2a0 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 20  .** rowid value 
1c2b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1c2c0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1c2d0 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 72  owid()] before r
1c2e0 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e  eturning .** con
1c2f0 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 72  trol to the user
1c300 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
1c310 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
1c320 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1c330 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
1c340 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75  ne will .** retu
1c350 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
1c360 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 72  f the inserted r
1c370 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
1c380 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a 2a  e trigger is .**
1c390 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74   running. Once t
1c3a0 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1c3b0 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  am ends, the val
1c3c0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1c3d0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1c3e0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1c3f0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1c400 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 69  e trigger was fi
1c410 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
1c420 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
1c430 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
1c440 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
1c450 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
1c460 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1c470 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
1c480 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1c490 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1c4a0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
1c4b0 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
1c4c0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
1c4d0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
1c4e0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
1c4f0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
1c500 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
1c510 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
1c520 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
1c530 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
1c540 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
1c550 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
1c560 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
1c570 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
1c580 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1c590 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
1c5a0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
1c5b0 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
1c5c0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
1c5d0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
1c5e0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
1c5f0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
1c600 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
1c610 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
1c620 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
1c630 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
1c640 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
1c650 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
1c660 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
1c670 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
1c680 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
1c690 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
1c6a0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
1c6b0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
1c6c0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
1c6d0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
1c6e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
1c6f0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
1c700 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
1c710 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
1c720 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
1c730 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1c740 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1c750 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
1c760 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
1c770 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
1c780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c790 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
1c7a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c7b0 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
1c7c0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
1c7d0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
1c7e0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
1c7f0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
1c800 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1c810 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c820 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c830 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
1c840 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
1c850 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
1c860 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
1c870 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
1c880 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
1c890 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1c8a0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1c8b0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1c8c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c8d0 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20 4c  I3REF: Set the L
1c8e0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1c8f0 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f   value..** METHO
1c900 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c910 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
1c920 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c930 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64 20  id(D, R) method 
1c940 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c 69  allows the appli
1c950 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74  cation to.** set
1c960 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1c970 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 73  ned by calling s
1c980 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1c990 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20 52  rt_rowid(D) to R
1c9a0 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e 73   .** without ins
1c9b0 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e 74  erting a row int
1c9c0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  o the database..
1c9d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1c9e0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1c9f0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73  rowid(sqlite3*,s
1ca00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
1ca10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ca20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
1ca30 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1ca40 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1ca50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ca60 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1ca70 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1ca80 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
1ca90 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
1caa0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
1cab0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1cac0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
1cad0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
1cae0 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
1caf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1cb00 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
1cb10 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
1cb20 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
1cb30 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1cb40 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1cb50 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
1cb60 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
1cb70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
1cb80 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
1cb90 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
1cba0 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
1cbb0 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
1cbc0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1cbd0 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
1cbe0 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
1cbf0 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
1cc00 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
1cc10 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1cc20 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
1cc30 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1cc40 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
1cc50 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1cc60 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
1cc70 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
1cc80 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1cc90 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1cca0 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
1ccb0 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
1ccc0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1ccd0 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
1cce0 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
1ccf0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1cd00 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1cd10 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
1cd20 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
1cd30 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
1cd40 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
1cd50 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
1cd60 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
1cd70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
1cd80 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
1cd90 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
1cda0 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
1cdb0 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
1cdc0 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
1cdd0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1cde0 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
1cdf0 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
1ce00 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
1ce10 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
1ce20 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
1ce30 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
1ce40 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1ce50 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
1ce60 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
1ce70 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1ce80 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
1ce90 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
1cea0 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
1ceb0 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
1cec0 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
1ced0 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
1cee0 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
1cef0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1cf00 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
1cf10 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1cf20 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
1cf30 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
1cf40 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
1cf50 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
1cf60 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
1cf70 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
1cf80 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
1cf90 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
1cfa0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
1cfb0 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
1cfc0 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
1cfd0 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
1cfe0 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
1cff0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1d000 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1d010 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
1d020 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
1d030 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
1d040 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
1d050 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
1d060 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
1d070 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
1d080 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
1d090 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1d0a0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1d0b0 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
1d0c0 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
1d0d0 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
1d0e0 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
1d0f0 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
1d100 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
1d110 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
1d120 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1d130 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
1d140 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
1d150 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
1d160 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1d170 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1d180 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
1d190 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
1d1a0 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
1d1b0 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
1d1c0 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
1d1d0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
1d1e0 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
1d1f0 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
1d200 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
1d210 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1d220 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
1d230 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
1d240 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
1d250 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1d260 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
1d270 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
1d280 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1d290 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1d2a0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1d2b0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
1d2c0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1d2d0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1d2e0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1d2f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d300 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1d310 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1d320 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1d330 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1d340 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1d350 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1d360 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a  t meaningful..**
1d370 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a  .** See also:.**
1d380 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68   <ul>.** <li> th
1d390 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1d3a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1d3b0 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68  rface.** <li> th
1d3c0 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  e [count_changes
1d3d0 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e   pragma].** <li>
1d3e0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1d3f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a  SQL function].**
1d400 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 5f   <li> the [data_
1d410 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a  version pragma].
1d420 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ul>.*/.int 
1d430 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1d440 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1d450 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1d460 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1d470 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1d480 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1d490 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1d4a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
1d4b0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
1d4c0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
1d4d0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
1d4e0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
1d4f0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
1d500 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
1d510 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
1d520 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
1d530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d540 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
1d550 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
1d560 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
1d570 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
1d580 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
1d590 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1d5a0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
1d5b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
1d5c0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
1d5d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d5e0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1d5f0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
1d600 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
1d610 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
1d620 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
1d630 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
1d640 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
1d650 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1d660 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
1d670 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1d680 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
1d690 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1d6a0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1d6b0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
1d6c0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
1d6d0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1d6e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1d6f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 44  _total_changes(D
1d700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  )] interface onl
1d710 79 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75  y reports the nu
1d720 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20  mber.** of rows 
1d730 74 68 61 74 20 63 68 61 6e 67 65 64 20 64 75 65  that changed due
1d740 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1d750 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20 64 61  t run against da
1d760 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
1d770 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68 61  tion D.  Any cha
1d780 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20 64 61  nges by other da
1d790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d7a0 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  ns are ignored..
1d7b0 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63 68 61  ** To detect cha
1d7c0 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61 20 64  nges against a d
1d7d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 72 6f  atabase file fro
1d7e0 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  m other database
1d7f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1d800 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d 41 20  use the [PRAGMA 
1d810 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f  data_version] co
1d820 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20  mmand or the.** 
1d830 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
1d840 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c  TA_VERSION] [fil
1d850 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a  e control]..** .
1d860 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1d870 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1d880 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1d890 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d8a0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1d8b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1d8c0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1d8d0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1d8e0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1d8f0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1d900 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1d910 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ul..**.** See al
1d920 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  so:.** <ul>.** <
1d930 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  li> the [sqlite3
1d940 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1d950 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68  rface.** <li> th
1d960 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  e [count_changes
1d970 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e   pragma].** <li>
1d980 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1d990 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a  SQL function].**
1d9a0 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61 5f   <li> the [data_
1d9b0 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a  version pragma].
1d9c0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c  ** <li> the [SQL
1d9d0 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
1d9e0 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f  ERSION] [file co
1d9f0 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ntrol].** </ul>.
1da00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1da10 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1da20 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1da30 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1da40 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1da50 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1da60 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1da70 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1da80 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1da90 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1daa0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1dab0 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1dac0 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1dad0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1dae0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1daf0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1db00 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1db10 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1db20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1db30 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1db40 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1db50 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1db60 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1db70 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1db80 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1db90 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1dba0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1dbb0 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1dbc0 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1dbd0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1dbe0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1dbf0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1dc00 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1dc10 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1dc20 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1dc30 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1dc40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dc50 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1dc60 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1dc70 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1dc80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1dc90 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1dca0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1dcb0 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1dcc0 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1dcd0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1dce0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1dcf0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1dd00 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1dd10 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1dd20 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1dd30 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1dd40 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1dd50 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1dd60 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1dd70 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1dd80 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1dd90 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1dda0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1ddb0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1ddc0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1ddd0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1dde0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1ddf0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1de00 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1de10 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1de20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1de30 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1de40 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1de50 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1de60 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1de70 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1de80 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1de90 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1dea0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1deb0 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1dec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ded0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1dee0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1def0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1df00 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1df10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1df20 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1df30 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1df40 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1df50 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1df60 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1df70 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1df80 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1df90 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1dfa0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1dfb0 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1dfc0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1dfd0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1dfe0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1dff0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1e000 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1e010 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1e020 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1e030 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1e040 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1e050 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1e060 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1e070 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1e080 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1e090 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1e0a0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1e0b0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1e0c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1e0d0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1e0e0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1e0f0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1e100 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64  returns..*/.void
1e110 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e120 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1e130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1e140 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1e150 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1e160 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1e170 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1e180 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1e190 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1e1a0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1e1b0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1e1c0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1e1d0 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1e1e0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1e1f0 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1e200 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1e210 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1e220 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1e230 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1e240 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1e250 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1e260 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1e270 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1e280 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1e290 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1e2a0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1e2b0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1e2c0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1e2d0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1e2e0 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1e2f0 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1e300 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1e310 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1e320 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1e330 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1e340 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1e350 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1e360 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1e370 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1e380 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1e390 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1e3a0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1e3b0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1e3c0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1e3d0 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1e3e0 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1e3f0 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1e400 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1e410 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1e420 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1e430 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1e440 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1e450 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1e460 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1e470 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1e480 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1e490 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1e4a0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1e4b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1e4c0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1e4d0 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1e4e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1e4f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1e500 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1e510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e520 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1e530 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1e540 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1e550 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1e560 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1e570 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1e580 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1e590 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1e5a0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1e5b0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1e5c0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1e5d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1e5e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1e5f0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1e600 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1e610 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1e620 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1e630 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1e640 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1e650 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1e660 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1e670 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1e680 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1e690 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1e6a0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1e6b0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1e6c0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1e6d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1e6e0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1e6f0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1e700 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1e710 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1e720 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e730 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1e740 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1e750 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1e760 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1e770 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1e780 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1e790 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1e7a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1e7b0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1e7c0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1e7d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1e7e0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1e7f0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1e800 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1e810 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1e820 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1e830 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1e840 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1e850 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1e860 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e870 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1e880 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1e890 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1e8a0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1e8b0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1e8c0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1e8d0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1e8e0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1e8f0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1e900 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1e910 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e920 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1e930 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1e940 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1e950 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1e960 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1e970 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1e980 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1e990 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1e9a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1e9b0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1e9c0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1e9d0 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1e9e0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1e9f0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1ea00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1ea10 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1ea20 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1ea30 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1ea40 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1ea50 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1ea60 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1ea70 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1ea80 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1ea90 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1eaa0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1eab0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1eac0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ead0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1eae0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1eaf0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1eb00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1eb10 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1eb20 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1eb30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1eb40 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1eb50 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1eb60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1eb70 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1eb80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1eb90 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1eba0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1ebb0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1ebc0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1ebd0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1ebe0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1ebf0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1ec00 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1ec10 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1ec20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1ec30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1ec40 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1ec50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ec60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1ec70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1ec80 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1ec90 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1eca0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1ecb0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1ecc0 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1ecd0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1ece0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1ecf0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1ed00 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1ed10 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1ed20 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1ed30 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1ed40 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1ed50 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1ed60 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1ed70 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1ed80 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1ed90 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1eda0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1edb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1edc0 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1edd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1ede0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1edf0 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1ee00 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1ee10 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1ee20 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1ee30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1ee40 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1ee50 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1ee60 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1ee70 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1ee80 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1ee90 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1eea0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1eeb0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1eec0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1eed0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1eee0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1eef0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1ef00 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1ef10 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1ef20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1ef30 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1ef40 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1ef50 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1ef60 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1ef70 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1ef80 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1ef90 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1efa0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1efb0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1efc0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1efd0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1efe0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1eff0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1f000 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1f010 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1f020 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1f030 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1f040 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1f050 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1f060 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1f070 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1f080 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1f090 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1f0a0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1f0b0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1f0c0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1f0d0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1f0e0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1f0f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f100 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1f110 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1f120 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1f130 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1f140 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1f150 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1f160 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1f170 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1f180 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1f190 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1f1a0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1f1b0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1f1c0 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1f1d0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1f1e0 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1f1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1f200 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1f210 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1f220 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1f230 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1f240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f250 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1f260 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1f270 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1f280 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1f290 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1f2a0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1f2b0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1f2c0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1f2d0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1f2e0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1f2f0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1f300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f310 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1f320 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1f330 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1f340 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1f350 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1f360 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1f370 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1f380 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1f390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1f3a0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1f3b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1f3c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1f3d0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1f3e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1f3f0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1f400 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1f410 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1f420 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1f430 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1f440 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1f450 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1f460 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1f470 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1f480 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1f490 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1f4a0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1f4b0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1f4c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1f4d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1f4e0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1f4f0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1f500 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1f510 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1f520 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1f530 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1f540 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1f550 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1f560 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1f570 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1f580 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1f590 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1f5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1f5b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1f5c0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1f5d0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1f5e0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1f5f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1f600 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1f610 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1f620 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1f630 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1f640 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1f650 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1f660 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1f670 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1f680 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1f690 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1f6a0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1f6b0 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1f6c0 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1f6d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1f6e0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1f6f0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1f700 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1f710 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1f720 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1f730 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1f740 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1f750 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1f760 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1f770 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1f780 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f790 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1f7a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1f7b0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1f7c0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1f7d0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1f7e0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1f7f0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1f800 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1f810 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1f820 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1f830 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1f840 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1f850 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1f860 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1f870 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1f880 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1f890 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1f8a0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1f8b0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1f8c0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1f8d0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1f8e0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1f8f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1f900 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1f910 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1f920 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1f930 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1f940 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1f950 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1f960 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1f970 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1f980 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1f990 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1f9a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f9b0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1f9c0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1f9d0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1f9e0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1f9f0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1fa00 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1fa10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1fa20 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1fa30 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1fa40 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1fa50 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1fa60 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1fa70 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1fa80 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1fa90 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1faa0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1fab0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1fac0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1fad0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1fae0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1faf0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1fb00 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1fb10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1fb20 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1fb30 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1fb40 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1fb50 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1fb60 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1fb70 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1fb80 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1fb90 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1fba0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1fbb0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1fbc0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1fbd0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1fbe0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1fbf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1fc00 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1fc10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1fc20 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1fc30 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1fc40 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1fc50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1fc60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1fc70 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1fc80 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1fc90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1fca0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1fcb0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1fcc0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1fcd0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1fce0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1fcf0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1fd00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1fd10 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1fd20 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1fd30 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1fd40 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1fd50 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1fd60 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1fd70 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1fd80 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1fd90 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1fda0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1fdb0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1fdc0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1fdd0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1fde0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1fdf0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1fe00 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1fe10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1fe20 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1fe30 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1fe40 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1fe50 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1fe60 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1fe70 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1fe80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1fe90 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1fea0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1feb0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1fec0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1fed0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1fee0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1fef0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1ff00 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1ff10 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1ff20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ff30 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1ff40 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1ff50 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1ff60 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1ff70 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1ff80 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1ff90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1ffa0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1ffb0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1ffc0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1ffd0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1ffe0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1fff0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
20000 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
20010 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
20020 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
20030 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
20040 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
20050 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
20060 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
20070 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
20080 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
20090 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
200a0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
200b0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
200c0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
200d0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
200e0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
200f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20100 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
20110 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20120 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
20130 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
20140 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
20150 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20160 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
20170 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
20180 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
20190 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
201a0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
201b0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
201c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
201d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
201e0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
201f0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
20200 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
20210 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
20220 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
20230 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
20240 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
20250 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
20260 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
20270 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
20280 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
20290 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
202a0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
202b0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
202c0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
202d0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
202e0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
202f0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
20300 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
20310 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
20320 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
20330 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
20340 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
20350 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
20360 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
20370 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
20380 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
20390 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
203a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
203b0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
203c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
203d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
203e0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
203f0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
20400 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
20410 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
20420 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
20430 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
20440 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
20450 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
20460 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
20470 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
20480 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
20490 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
204a0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
204b0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
204c0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
204d0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
204e0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
204f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
20500 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
20510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20520 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
20530 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
20540 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
20550 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
20560 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
20570 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
20580 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
20590 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
205a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
205b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
205c0 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
205d0 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66   of the common f
205e0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
205f0 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  s from.** the st
20600 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70  andard library p
20610 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73  rintf() .** plus
20620 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
20630 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
20640 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51  rmats ([%q], [%Q
20650 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a  ], [%w], and [%z
20660 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  ])..** See the [
20670 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28  built-in printf(
20680 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
20690 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a   for details..**
206a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
206b0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
206c0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
206d0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
206e0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
206f0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
20700 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
20710 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
20720 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
20730 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
20740 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
20750 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
20760 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
20770 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
20780 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
20790 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
207a0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
207b0 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75  malloc64()] is u
207c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
207d0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
207e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
207f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
20800 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
20810 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
20820 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
20830 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
20840 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
20850 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
20860 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
20870 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
20880 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
20890 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
208a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
208b0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
208c0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
208d0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
208e0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
208f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
20900 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
20910 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
20920 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
20930 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
20940 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
20950 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
20960 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
20970 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
20980 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
20990 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
209a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
209b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
209c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
209d0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
209e0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
209f0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
20a00 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
20a10 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
20a20 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
20a30 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
20a40 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
20a50 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
20a60 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
20a70 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
20a80 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
20a90 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
20aa0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
20ab0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
20ac0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
20ad0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
20ae0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
20af0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
20b00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
20b10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
20b20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20b30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
20b40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
20b50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
20b60 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
20b70 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
20b80 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
20b90 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
20ba0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
20bb0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
20bc0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
20bd0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
20be0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
20bf0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
20c00 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
20c10 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
20c20 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
20c30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
20c40 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
20c50 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
20c60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
20c70 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  intf()..**.** Se
20c80 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d  e also:  [built-
20c90 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70  in printf()], [p
20ca0 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63  rintf() SQL func
20cb0 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion].*/.char *s
20cc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
20cd0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
20ce0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
20cf0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
20d00 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
20d10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
20d20 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20d30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
20d40 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
20d50 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
20d60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
20d70 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
20d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
20d90 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
20da0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
20db0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
20dc0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
20dd0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
20de0 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
20df0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
20e00 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
20e10 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
20e20 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
20e30 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
20e40 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
20e50 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
20e60 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
20e70 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
20e80 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
20e90 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
20ea0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
20eb0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
20ec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
20ed0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
20ee0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
20ef0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
20f00 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
20f10 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
20f20 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
20f30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
20f40 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
20f50 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
20f60 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
20f70 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
20f80 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
20f90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20fa0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
20fb0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
20fc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
20fd0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
20fe0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
20ff0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
21000 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
21010 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
21020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
21030 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
21040 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
21050 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
21060 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
21070 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
21080 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
21090 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
210a0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
210b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
210c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
210d0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
210e0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
210f0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
21100 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
21110 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
21120 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
21130 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
21140 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
21150 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
21160 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
21170 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
21180 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
21190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
211a0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
211b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
211c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
211d0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
211e0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
211f0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
21200 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
21210 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
21220 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
21230 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
21240 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
21250 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
21260 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
21270 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
21280 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
21290 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
212a0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
212b0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
212c0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
212d0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
212e0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
212f0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
21300 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
21310 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
21320 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
21330 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
21340 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
21350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
21360 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
21370 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
21380 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
21390 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
213a0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
213b0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
213c0 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
213d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
213e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
213f0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
21400 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
21410 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
21420 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
21430 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21440 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
21450 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21460 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21470 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
21480 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
21490 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
214a0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
214b0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
214c0 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
214d0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
214e0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
214f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
21500 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21510 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
21520 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
21530 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
21540 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
21550 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
21560 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
21570 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
21580 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
21590 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
215a0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
215b0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
215c0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
215d0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
215e0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
215f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21600 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
21610 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
21620 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
21630 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21640 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
21650 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
21660 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
21670 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
21680 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
21690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
216a0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
216b0 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
216c0 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
216d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
216e0 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
216f0 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
21700 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
21710 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
21720 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
21730 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
21740 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
21750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
21760 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
21770 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
21780 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
21790 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
217a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
217b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
217c0 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
217d0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
217e0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
217f0 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
21800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
21810 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
21820 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
21830 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
21840 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
21850 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
21860 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
21870 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
21880 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
21890 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
218a0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
218b0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
218c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
218d0 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
218e0 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
218f0 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
21900 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
21910 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
21920 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
21930 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
21940 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
21950 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
21960 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
21970 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
21980 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
21990 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
219a0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
219b0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
219c0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
219d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
219e0 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
219f0 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
21a00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
21a10 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
21a20 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
21a30 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
21a40 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
21a50 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
21a60 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
21a70 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
21a80 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
21a90 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
21aa0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
21ab0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
21ac0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
21ad0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
21ae0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
21af0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
21b00 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
21b10 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
21b20 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
21b30 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
21b40 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
21b50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
21b60 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
21b70 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
21b80 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
21b90 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
21ba0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
21bb0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
21bc0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
21bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
21be0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
21bf0 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
21c00 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
21c10 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
21c20 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
21c30 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
21c40 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
21c50 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
21c60 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
21c70 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
21c80 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
21c90 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
21ca0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
21cb0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
21cc0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
21cd0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
21ce0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
21cf0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
21d00 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
21d10 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
21d20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
21d30 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
21d40 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
21d50 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
21d60 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
21d70 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
21d80 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
21d90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
21da0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
21db0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
21dc0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
21dd0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
21de0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
21df0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
21e00 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
21e10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
21e20 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
21e30 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
21e40 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
21e50 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
21e60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
21e70 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
21e80 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
21e90 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
21ea0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
21eb0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
21ec0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
21ed0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
21ee0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
21ef0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
21f00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
21f10 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
21f20 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
21f30 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
21f40 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
21f50 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
21f60 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
21f70 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
21f80 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
21f90 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
21fa0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
21fb0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
21fc0 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
21fd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
21fe0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
21ff0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
22000 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
22010 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
22020 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
22030 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
22040 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
22050 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
22060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
22070 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
22080 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
22090 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
220a0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
220b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
220c0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
220d0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
220e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
220f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
22100 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
22110 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
22120 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
22130 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
22140 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
22150 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
22160 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
22170 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
22180 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
22190 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
221a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
221b0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
221c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
221d0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
221e0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
221f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
22200 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
22210 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
22220 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
22230 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
22240 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
22250 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
22260 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
22270 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
22280 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
22290 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
222a0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
222b0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
222c0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
222d0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
222e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
222f0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
22300 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
22310 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
22320 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
22330 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
22340 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
22350 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
22360 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
22370 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
22380 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
22390 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
223a0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
223b0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
223c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
223d0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
223e0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
223f0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
22400 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
22410 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
22420 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
22430 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
22440 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
22450 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
22460 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
22470 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
22480 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
22490 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
224a0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
224b0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
224c0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
224d0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
224e0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
224f0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
22500 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
22510 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
22520 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
22530 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
22540 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
22550 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
22560 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
22570 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
22580 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
22590 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
225a0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
225b0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
225c0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
225d0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
225e0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
225f0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
22600 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
22610 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
22620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
22630 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
22640 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
22650 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
22660 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
22670 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
22680 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
22690 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
226a0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
226b0 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
226c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
226d0 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
226e0 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
226f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
22700 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
22710 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
22720 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
22730 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
22740 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
22750 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
22760 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
22770 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
22780 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
22790 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
227a0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
227b0 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
227c0 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
227d0 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
227e0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
227f0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
22800 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
22810 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
22820 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
22830 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
22840 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
22850 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
22860 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
22870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22880 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
22890 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
228a0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
228b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45  D: sqlite3.** KE
228c0 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69  YWORDS: {authori
228d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a  zer callback}.**
228e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
228f0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
22900 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22910 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
22920 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
22930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
22940 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
22950 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
22960 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
22970 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
22980 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
22990 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
229a0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
229b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
229c0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
229d0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
229e0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
229f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22a00 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
22a10 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b  _prepare16()], [
22a20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22a30 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  6_v2()],.** and 
22a40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22a50 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76  16_v3()].  ^At v
22a60 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
22a70 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
22a80 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
22a90 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
22aa0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
22ab0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
22ac0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
22ad0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22ae0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
22af0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
22b00 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
22b10 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
22b20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
22b30 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
22b40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
22b50 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
22b60 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
22b70 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
22b80 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
22b90 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
22ba0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22bb0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
22bc0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
22bd0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
22be0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
22bf0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
22c00 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
22c10 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
22c20 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
22c30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22c40 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
22c50 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
22c60 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
22c70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
22c80 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
22c90 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
22ca0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22cb0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
22cc0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
22cd0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
22ce0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
22cf0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
22d00 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
22d10 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
22d20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
22d30 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
22d40 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
22d50 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
22d60 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
22d70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
22d80 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
22d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
22da0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
22db0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
22dc0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
22dd0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
22de0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
22df0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
22e00 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
22e10 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
22e20 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
22e30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
22e40 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
22e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
22e60 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
22e70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
22e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
22e90 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
22ea0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
22eb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
22ec0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
22ed0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
22ee0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
22ef0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
22f00 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
22f10 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
22f20 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
22f30 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
22f40 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
22f50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
22f60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
22f70 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69   either NULL poi
22f80 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65  nters or zero-te
22f90 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
22fa0 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  .** that contain
22fb0 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
22fc0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
22fd0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
22fe0 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63  rized..** Applic
22ff0 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61  ations must alwa
23000 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74  ys be prepared t
23010 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55  o encounter a NU
23020 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e  LL pointer in an
23030 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72  y.** of the thir
23040 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69  d through the si
23050 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f  xth parameters o
23060 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  f the authorizat
23070 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
23080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
23090 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
230a0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
230b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
230c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
230d0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
230e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
230f0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
23100 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
23110 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
23120 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
23130 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
23140 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
23150 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
23160 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
23170 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
23180 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
23190 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
231a0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
231b0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
231c0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
231d0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
231e0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
231f0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68   a table..** ^Wh
23200 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65  en a table is re
23210 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53  ferenced by a [S
23220 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f  ELECT] but no co
23230 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a  lumn values are.
23240 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  ** extracted fro
23250 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f  m that table (fo
23260 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71  r example in a q
23270 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45  uery like.** "SE
23280 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52  LECT count(*) FR
23290 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68  OM tab") then th
232a0 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  e [SQLITE_READ] 
232b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
232c0 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ack.** is invoke
232d0 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20  d once for that 
232e0 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c  table with a col
232f0 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73  umn name that is
23300 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23310 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
23320 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
23330 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
23340 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
23350 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
23360 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
23370 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
23380 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
23390 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
233a0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
233b0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
233c0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
233d0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
233e0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
233f0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
23400 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
23410 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
23420 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
23430 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
23440 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
23450 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
23460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
23470 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
23480 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
23490 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
234a0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
234b0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
234c0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
234d0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
234e0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
234f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
23500 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
23510 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
23520 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
23530 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
23540 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
23550 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
23560 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
23570 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
23580 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
23590 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
235a0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
235b0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
235c0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
235d0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
235e0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
235f0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
23600 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
23610 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
23620 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
23630 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
23640 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
23650 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
23660 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
23670 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
23680 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
23690 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
236a0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
236b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
236c0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
236d0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
236e0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
236f0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
23700 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
23710 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
23720 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
23730 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
23740 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
23750 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
23760 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
23770 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
23780 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
23790 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
237a0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
237b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
237c0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
237d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
237e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
237f0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
23800 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
23810 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
23820 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
23830 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
23840 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
23850 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
23860 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
23870 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
23880 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23890 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
238a0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
238b0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
238c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
238d0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
238e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
238f0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
23900 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23910 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23920 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23930 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
23940 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
23950 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23960 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23970 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
23980 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
23990 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
239a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
239b0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
239c0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
239d0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
239e0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
239f0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
23a00 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
23a10 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
23a20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
23a30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
23a40 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
23a50 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
23a60 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
23a70 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
23a80 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
23a90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23aa0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
23ab0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
23ac0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23ad0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
23ae0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
23af0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
23b00 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
23b10 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
23b20 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
23b30 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
23b40 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
23b50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
23b60 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
23b70 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
23b80 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
23b90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
23ba0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
23bb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
23bc0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
23bd0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
23be0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
23bf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
23c00 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
23c10 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
23c20 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
23c30 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
23c40 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
23c50 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
23c60 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
23c70 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
23c80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
23c90 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
23ca0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
23cb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23cc0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
23cd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23ce0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
23cf0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
23d00 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
23d10 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
23d20 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
23d30 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
23d40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23d50 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
23d60 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
23d70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
23d80 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
23d90 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
23da0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
23db0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
23dc0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
23dd0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
23de0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
23df0 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
23e00 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
23e10 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
23e20 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
23e30 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
23e40 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
23e50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23e60 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
23e70 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
23e80 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
23e90 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
23ea0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
23eb0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
23ec0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
23ed0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
23ee0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
23ef0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
23f00 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
23f10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
23f20 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23f30 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
23f40 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
23f50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
23f60 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
23f70 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
23f80 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
23f90 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
23fa0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
23fb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
23fc0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
23fd0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
23fe0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
23ff0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
24000 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
24010 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
24020 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
24030 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
24040 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
24050 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
24060 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
24070 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
24080 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
24090 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
240a0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
240b0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
240c0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
240d0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
240e0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
240f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
24100 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
24110 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
24120 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
24130 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
24140 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
24150 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
24160 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
24170 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
24180 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
24190 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
241a0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
241b0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
241c0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
241d0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
241e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
241f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
24200 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
24210 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
24220 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
24230 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
24240 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
24250 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
24260 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
24270 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
24280 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
24290 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
242a0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
242b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
242c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
242d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
242e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
242f0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
24300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24310 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
24320 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
24330 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
24340 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24360 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
24370 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
24380 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24390 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
243a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
243b0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
243c0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
243d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
243e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
243f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24400 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
24410 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
24420 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
24430 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24440 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24450 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
24460 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
24470 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
24480 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24490 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
244a0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
244b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
244c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
244d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
244e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
244f0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
24500 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
24510 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
24520 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24530 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
24540 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
24550 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
24560 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24580 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
24590 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
245a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
245b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
245c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
245d0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
245e0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
245f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
24600 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24620 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
24630 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
24640 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24650 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24670 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
24680 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
24690 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
246a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
246b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
246c0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
246d0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
246e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
246f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24710 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
24720 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
24730 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
24740 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24760 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
24770 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
24780 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
24790 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
247a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
247b0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
247c0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
247d0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
247e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
247f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24800 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
24810 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
24820 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
24830 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24840 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
24850 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
24860 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
24870 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24880 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24890 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
248a0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
248b0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
248c0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
248d0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
248e0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
248f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
24900 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
24910 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
24920 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24930 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
24940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
24950 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
24960 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24980 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
24990 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
249a0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
249b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
249c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
249d0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
249e0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
249f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24a00 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
24a10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24a20 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
24a30 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
24a40 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
24a50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24a60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24a70 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
24a80 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
24a90 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
24aa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24ac0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
24ad0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
24ae0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
24af0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24b10 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
24b20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
24b30 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
24b40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24b60 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
24b70 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
24b80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
24b90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24bb0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
24bc0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
24bd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
24be0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
24bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24c00 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
24c10 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
24c20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
24c30 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
24c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
24c50 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
24c60 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
24c70 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
24c80 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
24c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
24ca0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
24cb0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
24cc0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
24cd0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
24ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
24cf0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
24d00 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
24d10 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
24d20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
24d30 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
24d40 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
24d50 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
24d60 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
24d70 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
24d80 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
24d90 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
24da0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24db0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24dc0 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
24dd0 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
24de0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
24df0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
24e00 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
24e10 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
24e20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
24e30 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
24e40 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
24e50 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
24e60 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
24e70 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
24e80 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
24e90 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
24ea0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
24eb0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24ec0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
24ed0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24ee0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
24ef0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
24f00 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
24f10 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
24f20 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
24f30 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
24f40 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
24f50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24f60 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
24f70 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
24f80 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
24f90 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
24fa0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
24fb0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
24fc0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
24fd0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24fe0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
24ff0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
25000 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
25010 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
25020 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
25030 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
25040 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
25050 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
25060 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
25070 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
25080 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
25090 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
250a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
250b0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
250c0 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
250d0 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
250e0 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
250f0 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
25100 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
25110 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
25120 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
25130 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
25140 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
25150 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
25160 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
25170 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
25180 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
25190 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
251a0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
251b0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
251c0 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
251d0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
251e0 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
251f0 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
25200 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
25210 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
25220 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
25230 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
25240 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
25250 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
25260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
25270 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
25280 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
25290 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
252a0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
252b0 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
252c0 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
252d0 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
252e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
252f0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
25300 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
25310 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
25320 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
25330 61 6c 6c 62 61 63 6b 2e 20 20 49 6e 76 6f 6b 69  allback.  Invoki
25340 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 5b 73 71  ng.** either [sq
25350 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f  lite3_trace()] o
25360 72 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  r [sqlite3_trace
25370 5f 76 32 28 29 5d 20 77 69 6c 6c 20 63 61 6e 63  _v2()] will canc
25380 65 6c 20 74 68 65 0a 2a 2a 20 70 72 6f 66 69 6c  el the.** profil
25390 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a 53  e callback..*/.S
253a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
253b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
253c0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
253d0 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
253e0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
253f0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
25400 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
25410 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
25420 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
25430 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
25440 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
25450 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
25460 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
25470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
25480 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
25490 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
254a0 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
254b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
254c0 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
254d0 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
254e0 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
254f0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
25500 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
25510 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
25520 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67 75  gic.  The M argu
25530 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
25540 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
25550 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d  ,X,P)] is an OR-
25560 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
25570 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
25580 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
25590 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
255a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
255b0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
255c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
255d0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
255e0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
255f0 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
25600 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
25610 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
25620 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
25630 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
25640 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
25650 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
25660 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
25670 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
25680 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
25690 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
256a0 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
256b0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
256c0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
256d0 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
256e0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
256f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
25700 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
25710 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
25720 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
25730 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
25740 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
25750 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
25760 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
25770 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
25780 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
25790 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
257a0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
257b0 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
257c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
257d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257e0 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
257f0 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
25800 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
25810 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
25820 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
25830 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
25840 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
25850 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
25860 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
25870 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
25880 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
25890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
258a0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
258b0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
258c0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
258d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
258e0 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
258f0 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
25900 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
25910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25920 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
25930 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
25940 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
25950 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
25960 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
25970 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
25980 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
25990 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
259a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
259b0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
259c0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
259d0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
259e0 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
259f0 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
25a00 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
25a10 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
25a20 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
25a30 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
25a40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
25a50 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
25a60 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25a70 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
25a80 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
25a90 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
25aa0 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
25ab0 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
25ac0 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
25ad0 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
25ae0 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
25af0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
25b00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
25b10 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
25b20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
25b30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25b40 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
25b50 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
25b60 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
25b70 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
25b80 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
25b90 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
25ba0 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
25bb0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25bc0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
25bd0 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
25be0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
25bf0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
25c00 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
25c10 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
25c20 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
25c30 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
25c40 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
25c50 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
25c60 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
25c70 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
25c80 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
25c90 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
25ca0 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
25cb0 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
25cc0 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
25cd0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25ce0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25cf0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25d00 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
25d10 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
25d20 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
25d30 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
25d40 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
25d50 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
25d60 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
25d70 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25d80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25d90 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
25da0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
25db0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
25dc0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
25dd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25de0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25df0 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
25e00 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
25e10 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
25e20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
25e30 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
25e40 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
25e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25e60 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
25e70 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
25e80 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
25e90 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
25ea0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25eb0 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
25ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25ed0 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
25ee0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
25ef0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
25f00 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
25f10 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
25f20 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
25f30 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
25f40 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
25f50 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
25f60 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
25f70 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
25f80 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
25f90 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
25fa0 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
25fb0 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
25fc0 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
25fd0 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
25fe0 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
25ff0 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
26000 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
26010 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
26020 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
26030 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
26040 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
26050 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
26060 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
26070 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
26080 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
26090 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
260a0 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
260b0 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
260c0 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
260d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
260e0 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
260f0 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
26100 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
26110 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
26120 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
26130 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
26140 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
26150 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
26160 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
26170 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
26180 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
26190 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
261a0 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
261b0 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
261c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
261d0 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
261e0 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
261f0 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
26200 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
26210 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
26220 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
26230 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
26240 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
26250 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
26260 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
26270 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
26280 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
26290 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
262a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
262b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
262c0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
262d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
262e0 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
262f0 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
26300 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
26310 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
26320 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
26330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26340 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
26350 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
26360 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
26370 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
26380 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
26390 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
263a0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
263b0 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
263c0 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
263d0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
263e0 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
263f0 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
26400 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
26410 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
26420 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
26430 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
26440 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
26450 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
26460 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
26470 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
26480 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
26490 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
264a0 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
264b0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
264c0 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
264d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
264e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
264f0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
26500 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
26510 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
26520 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
26530 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
26540 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
26550 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
26560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26570 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
26580 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
26590 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
265a0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
265b0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
265c0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
265d0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
265e0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
265f0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
26600 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26610 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
26620 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
26630 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
26640 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
26650 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
26660 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
26670 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
26680 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
26690 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
266a0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
266b0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
266c0 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
266d0 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
266e0 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
266f0 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
26700 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
26710 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
26720 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
26730 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
26740 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
26750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26760 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
26770 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
26780 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
26790 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
267a0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
267b0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
267c0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
267d0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
267e0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
267f0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
26800 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
26810 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
26820 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
26830 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
26840 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
26850 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
26860 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
26870 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
26880 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
26890 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
268a0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
268b0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
268c0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
268d0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
268e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
268f0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
26900 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
26910 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
26920 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
26930 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
26940 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
26950 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
26960 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
26970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26980 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26990 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
269a0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
269b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
269c0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
269d0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
269e0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
269f0 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
26a00 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
26a10 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
26a20 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
26a30 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
26a40 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
26a50 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
26a60 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
26a70 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
26a80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
26a90 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
26aa0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
26ab0 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
26ac0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
26ad0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
26ae0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
26af0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
26b00 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
26b10 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
26b20 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26b30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
26b40 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
26b50 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
26b60 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
26b70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
26b80 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
26b90 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
26ba0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
26bb0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
26bc0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
26bd0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
26be0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
26bf0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
26c00 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
26c10 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
26c20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
26c30 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
26c40 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
26c50 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
26c60 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
26c70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
26c80 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
26c90 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
26ca0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26cb0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
26cc0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
26cd0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
26ce0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
26cf0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
26d00 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26d10 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
26d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
26d30 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
26d40 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
26d50 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
26d60 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
26d70 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
26d80 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
26d90 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
26da0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
26db0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
26dc0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
26dd0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
26de0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
26df0 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
26e00 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
26e10 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
26e20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
26e30 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
26e40 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
26e50 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
26e60 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
26e70 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
26e80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26e90 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
26ea0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
26eb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
26ec0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
26ed0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
26ee0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
26ef0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
26f00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
26f10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
26f20 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
26f30 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
26f40 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
26f50 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
26f60 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
26f70 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
26f80 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
26f90 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
26fa0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
26fb0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
26fc0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
26fd0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
26fe0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
26ff0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
27000 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
27010 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
27020 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
27030 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
27040 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
27050 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
27060 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
27070 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
27080 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
27090 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
270a0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
270b0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
270c0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
270d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
270e0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
270f0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
27100 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
27110 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
27120 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
27130 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
27140 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
27150 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
27160 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
27170 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
27180 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27190 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
271a0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
271b0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
271c0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
271d0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
271e0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
271f0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
27200 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
27210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27220 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27230 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
27240 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
27250 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
27260 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
27270 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
27280 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
27290 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
272a0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
272b0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
272c0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
272d0 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
272e0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
272f0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
27300 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
27310 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
27320 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
27330 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
27340 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
27350 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
27360 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
27370 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
27380 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
27390 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
273a0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
273b0 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
273c0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
273d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
273e0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
273f0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
27400 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
27410 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
27420 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27430 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
27440 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
27450 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
27460 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
27470 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
27480 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
27490 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
274a0 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
274b0 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
274c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
274d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
274e0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
274f0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
27500 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
27510 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27520 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
27530 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
27540 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
27550 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
27560 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
27570 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
27580 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
27590 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
275a0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
275b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
275c0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
275d0 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
275e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
275f0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
27600 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
27610 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
27620 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
27630 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
27640 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
27650 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
27660 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
27670 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
27680 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
27690 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
276a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
276b0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
276c0 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
276d0 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
276e0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
276f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27700 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
27710 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
27720 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
27730 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
27740 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
27750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27760 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
27770 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
27780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
27790 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
277a0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
277b0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
277c0 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
277d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
277e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
277f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27800 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
27810 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
27820 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
27830 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
27840 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
27850 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
27860 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
27870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
27880 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
27890 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
278a0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
278b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
278c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
278d0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
278e0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
278f0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
27900 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
27910 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
27920 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
27930 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
27940 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
27950 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
27960 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
27970 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
27980 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
27990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
279a0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
279b0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
279c0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
279d0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
279e0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
279f0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
27a00 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
27a10 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
27a20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
27a30 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
27a40 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27a50 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
27a60 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
27a70 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
27a80 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
27a90 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
27aa0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
27ab0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
27ac0 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
27ad0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
27ae0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
27af0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
27b00 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
27b10 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
27b20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
27b30 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
27b40 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
27b50 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
27b60 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
27b70 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
27b80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27b90 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
27ba0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
27bb0 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
27bc0 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
27bd0 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
27be0 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
27bf0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
27c00 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
27c10 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
27c20 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
27c30 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
27c40 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
27c50 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
27c60 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
27c70 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
27c80 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
27c90 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
27ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
27cb0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
27cc0 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69  * set in the thi
27cd0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
27ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27cf0 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
27d00 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
27d10 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
27d20 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
27d30 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
27d40 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
27d50 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
27d60 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
27d70 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
27d80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
27d90 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  n..** URI filena
27da0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
27db0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
27dc0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
27dd0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
27de0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
27df0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
27e00 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
27e10 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
27e20 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
27e30 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
27e40 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
27e50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
27e60 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
27e70 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
27e80 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
27e90 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
27ea0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
27eb0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
27ec0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
27ed0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
27ee0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
27ef0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
27f00 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
27f10 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
27f20 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
27f30 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
27f40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
27f50 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
27f60 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
27f70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
27f80 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
27f90 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
27fa0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
27fb0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
27fc0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
27fd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
27fe0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
27ff0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
28000 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
28010 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
28020 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
28030 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
28040 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
28050 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
28060 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
28070 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
28080 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
28090 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
280a0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
280b0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
280c0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
280d0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
280e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
280f0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
28100 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
28110 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
28120 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
28130 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
28140 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
28150 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
28160 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
28170 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
28180 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
28190 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
281a0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
281b0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
281c0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
281d0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
281e0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
281f0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
28200 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
28210 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
28220 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
28230 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
28240 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
28250 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
28260 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
28270 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
28280 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
28290 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
282a0 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
282b0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
282c0 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
282d0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
282e0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
282f0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
28300 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
28310 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
28320 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
28330 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
28340 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
28350 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
28360 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
28370 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
28380 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
28390 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
283a0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
283b0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
283c0 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
283d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
283e0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
283f0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
28400 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
28410 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
28420 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
28430 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
28440 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
28450 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
28460 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28470 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28480 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
28490 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
284a0 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
284b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
284c0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
284d0 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
284e0 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
284f0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
28500 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
28510 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
28520 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
28530 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
28540 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
28550 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
28560 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
28570 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
28580 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
28590 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
285a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
285b0 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
285c0 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
285d0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
285e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
285f0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
28600 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
28610 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
28620 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
28630 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
28640 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
28650 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
28660 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
28670 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
28680 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
28690 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
286a0 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
286b0 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
286c0 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
286d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
286e0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
286f0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
28700 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
28710 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
28720 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
28730 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
28740 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
28750 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
28760 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
28770 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
28780 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
28790 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
287a0 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
287b0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
287c0 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
287d0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
287e0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
287f0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
28800 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
28810 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
28820 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
28830 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
28840 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28850 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
28860 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
28870 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
28880 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
28890 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
288a0 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
288b0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
288c0 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
288d0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
288e0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
288f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
28900 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
28910 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
28920 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
28930 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
28940 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28950 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
28960 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
28970 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
28980 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
28990 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
289a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
289b0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
289c0 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
289d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
289e0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
289f0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
28a00 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
28a10 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
28a20 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
28a30 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
28a40 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
28a50 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
28a60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
28a70 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
28a80 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
28a90 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
28aa0 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
28ab0 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
28ac0 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
28ad0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28ae0 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
28af0 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
28b00 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
28b10 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
28b20 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
28b30 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
28b40 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
28b50 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
28b60 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
28b70 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
28b80 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
28b90 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
28ba0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
28bb0 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
28bc0 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
28bd0 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
28be0 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
28bf0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
28c00 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
28c10 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
28c20 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
28c30 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
28c40 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
28c50 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
28c60 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
28c70 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
28c80 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
28c90 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
28ca0 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
28cb0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
28cc0 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
28cd0 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
28ce0 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
28cf0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
28d00 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
28d10 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
28d20 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
28d30 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
28d40 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
28d50 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
28d60 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
28d70 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
28d80 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
28d90 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
28da0 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
28db0 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
28dc0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
28dd0 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
28de0 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
28df0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
28e00 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
28e10 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
28e20 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
28e30 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
28e40 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
28e50 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
28e60 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
28e70 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
28e80 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
28e90 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
28ea0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
28eb0 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
28ec0 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
28ed0 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
28ee0 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
28ef0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
28f00 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
28f10 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
28f20 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
28f30 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
28f40 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
28f50 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
28f60 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
28f70 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
28f80 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
28f90 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
28fa0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
28fb0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
28fc0 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
28fd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
28fe0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
28ff0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
29000 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
29010 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
29020 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
29030 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
29040 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
29050 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
29060 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
29070 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
29080 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
29090 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
290a0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
290b0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
290c0 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
290d0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
290e0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
290f0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
29100 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
29110 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
29120 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
29130 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
29140 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
29150 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
29160 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
29170 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
29180 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
29190 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
291a0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
291b0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
291c0 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
291d0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
291e0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
291f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
29200 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
29210 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
29220 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
29230 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
29240 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
29250 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
29260 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
29270 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
29280 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
29290 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
292a0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
292b0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
292c0 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
292d0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
292e0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
292f0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
29300 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
29310 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
29320 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
29330 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
29340 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
29350 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
29360 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
29370 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
29380 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
29390 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
293a0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
293b0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
293c0 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
293d0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
293e0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
293f0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
29400 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
29410 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
29420 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
29430 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
29440 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
29450 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
29460 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
29470 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
29480 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
29490 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
294a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
294b0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
294c0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
294d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
294e0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
294f0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
29500 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
29510 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
29520 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
29530 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
29540 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
29550 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
29560 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
29570 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
29580 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
29590 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
295a0 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
295b0 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
295c0 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
295d0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
295e0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
295f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
29600 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
29610 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
29620 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
29630 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
29640 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
29650 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
29660 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
29670 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
29680 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
29690 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
296a0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
296b0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
296c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
296d0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
296e0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
296f0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
29700 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
29710 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
29720 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
29730 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
29740 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
29750 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
29760 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
29770 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
29780 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
29790 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
297a0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
297b0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
297c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
297d0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
297e0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
297f0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
29800 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
29810 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
29820 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
29830 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
29840 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
29850 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
29860 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
29870 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
29880 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
29890 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
298a0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
298b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
298c0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
298d0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
298e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
298f0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
29900 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
29910 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
29920 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
29930 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
29940 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
29950 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
29960 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
29970 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
29980 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
29990 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
299a0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
299b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
299c0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
299d0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
299e0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
299f0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
29a00 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
29a10 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
29a20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
29a30 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
29a40 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
29a50 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
29a60 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
29a70 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
29a80 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
29a90 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
29aa0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29ab0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
29ac0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29ad0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
29ae0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
29af0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
29b00 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
29b10 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
29b20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
29b30 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
29b40 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
29b50 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
29b60 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
29b70 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
29b80 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
29b90 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
29ba0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
29bb0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
29bc0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
29bd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
29be0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
29bf0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
29c00 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
29c10 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
29c20 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
29c30 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
29c40 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
29c50 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
29c60 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
29c70 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
29c80 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
29c90 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
29ca0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
29cb0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
29cc0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
29cd0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
29ce0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
29cf0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
29d00 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
29d10 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
29d20 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
29d30 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
29d40 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
29d50 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
29d60 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
29d70 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
29d80 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
29d90 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
29da0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
29db0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
29dc0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
29dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
29de0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
29df0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
29e00 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
29e10 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
29e20 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
29e30 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
29e40 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
29e50 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
29e60 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
29e70 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
29e80 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
29e90 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
29ea0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
29eb0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
29ec0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
29ed0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
29ee0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
29ef0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
29f00 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
29f10 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
29f20 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
29f30 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
29f40 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
29f50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
29f60 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
29f70 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
29f80 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
29f90 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
29fa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
29fb0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
29fc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
29fd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
29fe0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
29ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
2a000 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2a010 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
2a020 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
2a030 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
2a040 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
2a050 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
2a060 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
2a070 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
2a080 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
2a090 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
2a0a0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a0b0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
2a0c0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
2a0d0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
2a0e0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
2a0f0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
2a100 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
2a110 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
2a120 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
2a130 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
2a140 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
2a150 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a160 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
2a170 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
2a180 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
2a190 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2a1a0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
2a1b0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
2a1c0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
2a1d0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
2a1e0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
2a1f0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
2a200 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
2a210 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
2a220 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
2a230 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
2a240 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
2a250 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
2a260 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
2a270 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a280 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
2a290 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
2a2a0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
2a2b0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
2a2c0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
2a2d0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
2a2e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2a2f0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
2a300 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
2a310 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
2a320 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
2a330 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
2a340 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
2a350 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
2a360 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
2a370 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a380 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
2a390 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2a3a0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
2a3b0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
2a3c0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
2a3d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
2a3e0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
2a3f0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
2a400 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
2a410 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
2a420 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
2a430 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
2a440 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
2a450 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
2a460 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
2a470 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
2a480 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
2a490 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
2a4a0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
2a4b0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
2a4c0 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 55 52  *.** See the [UR
2a4d0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 64 6f 63 75  I filename] docu
2a4e0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2a4f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2a500 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  tion..*/.const c
2a510 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
2a520 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
2a530 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
2a540 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
2a550 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
2a560 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
2a570 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2a580 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
2a590 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
2a5a0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
2a5b0 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
2a5c0 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
2a5d0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2a5e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
2a5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a600 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
2a610 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
2a620 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
2a630 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2a640 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
2a650 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
2a660 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
2a670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a680 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
2a690 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
2a6a0 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
2a6b0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
2a6c0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
2a6d0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
2a6e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2a6f0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
2a700 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65  PI call..** ^The
2a710 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
2a720 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
2a730 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
2a740 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
2a750 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2a760 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
2a770 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2a780 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
2a790 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2a7a0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
2a7b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  d..**.** The val
2a7c0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2a7d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a7e0 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  ) and/or.** sqli
2a7f0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2a800 63 6f 64 65 28 29 20 6d 69 67 68 74 20 63 68 61  code() might cha
2a810 6e 67 65 20 77 69 74 68 20 65 61 63 68 20 41 50  nge with each AP
2a820 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70  I call..** Excep
2a830 74 2c 20 74 68 65 72 65 20 61 72 65 20 73 6f 6d  t, there are som
2a840 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 68 61  e interfaces tha
2a850 74 20 61 72 65 20 67 75 61 72 61 6e 74 65 65 64  t are guaranteed
2a860 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20 63 68 61   to never.** cha
2a870 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 6f 66  nge the value of
2a880 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 2e   the error code.
2a890 20 20 54 68 65 20 65 72 72 6f 72 2d 63 6f 64 65    The error-code
2a8a0 20 70 72 65 73 65 72 76 69 6e 67 0a 2a 2a 20 69   preserving.** i
2a8b0 6e 74 65 72 66 61 63 65 73 20 61 72 65 3a 0a 2a  nterfaces are:.*
2a8c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a8d0 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  > sqlite3_errcod
2a8e0 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  e().** <li> sqli
2a8f0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2a900 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  code().** <li> s
2a910 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 0a  qlite3_errmsg().
2a920 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
2a930 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20 3c 2f  errmsg16().** </
2a940 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ul>.**.** ^The s
2a950 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
2a960 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
2a970 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
2a980 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
2a990 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
2a9a0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
2a9b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
2a9c0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
2a9d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
2a9e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
2a9f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2aa00 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
2aa10 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
2aa20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2aa30 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2aa40 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
2aa50 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
2aa60 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
2aa70 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
2aa80 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
2aa90 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
2aaa0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
2aab0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
2aac0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
2aad0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
2aae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2aaf0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
2ab00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2ab10 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
2ab20 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
2ab30 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
2ab40 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
2ab50 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
2ab60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
2ab70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
2ab80 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
2ab90 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
2aba0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
2abb0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
2abc0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
2abd0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
2abe0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
2abf0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
2ac00 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
2ac10 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
2ac20 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
2ac30 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
2ac40 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
2ac50 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
2ac60 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
2ac70 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
2ac80 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2ac90 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
2aca0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
2acb0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
2acc0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
2acd0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
2ace0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
2acf0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
2ad00 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
2ad10 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
2ad20 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
2ad30 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
2ad40 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
2ad50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2ad60 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
2ad70 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
2ad80 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
2ad90 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
2ada0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
2adb0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
2adc0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
2add0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
2ade0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
2adf0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
2ae00 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
2ae10 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
2ae20 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
2ae30 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
2ae40 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2ae50 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
2ae60 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
2ae70 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
2ae80 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
2ae90 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
2aea0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
2aeb0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
2aec0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
2aed0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
2aee0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
2aef0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2af00 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
2af10 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
2af20 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
2af30 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2af40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2af50 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
2af60 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
2af70 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
2af80 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
2af90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2afa0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
2afb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2afc0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2afd0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
2afe0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
2aff0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
2b000 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b010 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
2b020 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
2b030 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
2b040 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
2b050 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
2b060 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
2b070 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
2b080 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
2b090 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
2b0a0 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
2b0b0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
2b0c0 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
2b0d0 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
2b0e0 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
2b0f0 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
2b100 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
2b110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b120 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
2b130 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
2b140 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
2b150 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
2b160 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
2b170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b180 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
2b190 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
2b1a0 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
2b1b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b1c0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
2b1d0 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
2b1e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2b1f0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
2b200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b210 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
2b220 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b230 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
2b240 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
2b250 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
2b260 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2b270 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
2b280 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
2b290 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
2b2a0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2b2b0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
2b2c0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2b2d0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
2b2e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b2f0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2b300 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
2b310 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
2b320 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
2b330 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
2b340 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
2b350 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
2b360 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
2b370 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2b380 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
2b390 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2b3a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
2b3b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
2b3c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
2b3d0 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
2b3e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
2b3f0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
2b400 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
2b410 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
2b420 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
2b430 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
2b440 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
2b450 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
2b460 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2b470 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
2b480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b490 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
2b4a0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
2b4b0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
2b4c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b4d0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
2b4e0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
2b4f0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
2b500 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
2b510 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
2b520 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
2b530 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
2b540 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
2b550 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
2b560 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
2b570 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
2b580 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
2b590 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
2b5a0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
2b5b0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
2b5c0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
2b5d0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
2b5e0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
2b5f0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
2b600 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
2b610 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
2b620 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
2b630 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
2b640 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
2b650 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
2b660 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
2b670 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
2b680 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
2b690 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
2b6a0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
2b6b0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
2b6c0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
2b6d0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2b6e0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
2b6f0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
2b700 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
2b710 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
2b720 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2b730 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
2b740 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
2b750 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
2b760 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
2b770 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2b780 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
2b790 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
2b7a0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
2b7b0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
2b7c0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
2b7d0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
2b7e0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
2b7f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
2b800 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
2b810 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
2b820 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
2b830 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
2b840 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
2b850 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
2b860 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
2b870 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
2b880 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
2b890 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
2b8a0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
2b8b0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
2b8c0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
2b8d0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
2b8e0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
2b8f0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
2b900 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
2b910 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
2b920 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
2b930 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
2b940 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
2b950 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
2b960 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
2b970 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
2b980 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
2b990 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
2b9a0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
2b9b0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
2b9c0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
2b9d0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
2b9e0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
2b9f0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2ba00 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
2ba10 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
2ba20 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
2ba30 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
2ba40 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
2ba50 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
2ba60 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
2ba70 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
2ba80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
2ba90 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
2baa0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
2bab0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
2bac0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
2bad0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
2bae0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
2baf0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
2bb00 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
2bb10 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
2bb20 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
2bb30 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
2bb40 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
2bb50 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
2bb60 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
2bb70 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2bb80 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
2bb90 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
2bba0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
2bbb0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
2bbc0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
2bbd0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
2bbe0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2bbf0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
2bc00 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
2bc10 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
2bc20 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
2bc30 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
2bc40 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
2bc50 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
2bc60 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
2bc70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
2bc80 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
2bc90 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
2bca0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
2bcb0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
2bcc0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
2bcd0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
2bce0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
2bcf0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
2bd00 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
2bd10 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
2bd20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bd30 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
2bd40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2bd50 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2bd60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
2bd70 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
2bd80 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
2bd90 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
2bda0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
2bdb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2bdc0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
2bdd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2bde0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2bdf0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
2be00 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
2be10 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
2be20 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
2be30 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2be40 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
2be50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2be60 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
2be70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2be80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2be90 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
2bea0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
2beb0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2bec0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
2bed0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2bee0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
2bef0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
2bf00 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
2bf10 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
2bf20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2bf30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2bf40 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2bf50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2bf60 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
2bf70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
2bf80 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
2bf90 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
2bfa0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
2bfb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2bfc0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2bfd0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
2bfe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2bff0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
2c000 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c010 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
2c020 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
2c030 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2c040 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
2c050 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2c060 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
2c070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2c080 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
2c090 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2c0a0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
2c0b0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
2c0c0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
2c0d0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
2c0e0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
2c0f0 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69  ement.  If [sqli
2c100 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c110 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69  ] or.** the equi
2c120 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20  valent tries to 
2c130 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66  allocate space f
2c140 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69  or more than thi
2c150 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a  s many opcodes.*
2c160 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72  * in a single pr
2c170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c180 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  , an SQLITE_NOME
2c190 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  M error is retur
2c1a0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
2c1b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2c1c0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
2c1d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c1e0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
2c1f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c200 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2c210 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
2c220 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
2c230 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c240 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
2c250 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c260 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
2c270 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2c280 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2c290 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
2c2a0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
2c2b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
2c2c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2c2d0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
2c2e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2c2f0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2c300 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
2c310 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c320 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
2c330 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
2c340 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
2c350 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
2c360 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
2c370 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c380 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2c390 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
2c3a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2c3b0 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
2c3c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c3d0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
2c3e0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
2c3f0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
2c400 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
2c410 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c420 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
2c430 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c440 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2c450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c460 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
2c470 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
2c480 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
2c490 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2c4a0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2c4b0 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
2c4c0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2c4d0 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
2c4e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2c4f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
2c500 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
2c510 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
2c520 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2c530 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
2c540 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
2c550 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
2c560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2c570 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2c580 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
2c590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
2c5a0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
2c5b0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2c5c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
2c5d0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
2c5e0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
2c5f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c600 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
2c610 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
2c620 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c630 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2c640 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
2c650 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c660 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
2c670 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
2c680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c690 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
2c6a0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
2c6b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c6c0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
2c6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
2c6e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c6f0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2c700 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
2c710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c720 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2c730 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
2c740 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
2c750 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2c760 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
2c770 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
2c780 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2c790 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
2c7a0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
2c7b0 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61  REF: Prepare Fla
2c7c0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
2c7d0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2c7e0 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68  various flags th
2c7f0 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  at can be passed
2c800 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c   into.** "prepFl
2c810 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f  ags" parameter o
2c820 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
2c830 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64  repare_v3()] and
2c840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c850 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74  pare16_v3()] int
2c860 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  erfaces..**.** N
2c870 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20  ew flags may be 
2c880 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
2c890 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2c8a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  te..**.** <dl>.*
2c8b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  * [[SQLITE_PREPA
2c8c0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20  RE_PERSISTENT]] 
2c8d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45  ^(<dt>SQLITE_PRE
2c8e0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c  PARE_PERSISTENT<
2c8f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c900 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2c910 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69  ERSISTENT flag i
2c920 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20  s a hint to the 
2c930 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a  query planner.**
2c940 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2c950 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2c960 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f  l be retained fo
2c970 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e  r a long time an
2c980 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65  d.** probably re
2c990 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e  used many times.
2c9a0 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73  )^ ^Without this
2c9b0 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f   flag, [sqlite3_
2c9c0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a  prepare_v3()].**
2c9d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2c9e0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73  epare16_v3()] as
2c9f0 73 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 72  sume that the pr
2ca00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ca10 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65   will .** be use
2ca20 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61  d just once or a
2ca30 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d  t most a few tim
2ca40 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74  es and then dest
2ca50 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
2ca60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ca70 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73  ()] relatively s
2ca80 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74  oon. The current
2ca90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2caa0 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20  acts.** on this 
2cab0 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67  hint by avoiding
2cac0 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f   the use of [loo
2cad0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73  kaside memory] s
2cae0 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64  o as not to.** d
2caf0 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74  eplete the limit
2cb00 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b  ed store of look
2cb10 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75  aside memory. Fu
2cb20 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
2cb30 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61  .** SQLite may a
2cb40 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ct on this hint 
2cb50 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a  differently..**.
2cb60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2cb70 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20  ARE_NORMALIZE]] 
2cb80 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2cb90 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74  RE_NORMALIZE</dt
2cba0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
2cbb0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2cbc0 41 4c 49 5a 45 20 66 6c 61 67 20 69 73 20 61 20  ALIZE flag is a 
2cbd0 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66 6c 61 67  no-op. This flag
2cbe0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72   used.** to be r
2cbf0 65 71 75 69 72 65 64 20 66 6f 72 20 61 6e 79 20  equired for any 
2cc00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cc10 6e 74 20 74 68 61 74 20 77 61 6e 74 65 64 20 74  nt that wanted t
2cc20 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  o use the.** [sq
2cc30 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64  lite3_normalized
2cc40 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  _sql()] interfac
2cc50 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65  e.  However, the
2cc60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72  .** [sqlite3_nor
2cc70 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69  malized_sql()] i
2cc80 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 77 20  nterface is now 
2cc90 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 61 6c 6c  available to all
2cca0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2ccb0 74 65 6d 65 6e 74 73 2c 20 72 65 67 61 72 64 6c  tements, regardl
2ccc0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2ccd0 72 20 6e 6f 74 20 74 68 65 79 20 75 73 65 20 74  r not they use t
2cce0 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a 2a 2a 0a  his.** flag..**.
2ccf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2cd00 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d 20 3c 64  ARE_NO_VTAB]] <d
2cd10 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2cd20 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e 0a 2a 2a  _NO_VTAB</dt>.**
2cd30 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
2cd40 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20  PREPARE_NO_VTAB 
2cd50 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
2cd60 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20  SQL compiler.** 
2cd70 74 6f 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  to return an err
2cd80 6f 72 20 28 65 72 72 6f 72 20 63 6f 64 65 20 53  or (error code S
2cd90 51 4c 49 54 45 5f 45 52 52 4f 52 29 20 69 66 20  QLITE_ERROR) if 
2cda0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
2cdb0 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72 74 75 61  es.** any virtua
2cdc0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f 64  l tables..** </d
2cdd0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2cde0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2cdf0 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20  SISTENT         
2ce00 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e       0x01.#defin
2ce10 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2ce20 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20 20 20  _NORMALIZE      
2ce30 20 20 20 20 20 20 20 20 20 30 78 30 32 0a 23 64           0x02.#d
2ce40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45  efine SQLITE_PRE
2ce50 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 20 20 20  PARE_NO_VTAB    
2ce60 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
2ce70 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
2ce80 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
2ce90 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2cea0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2ceb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
2cec0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
2ced0 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
2cee0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
2cef0 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
2cf00 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74  cute an SQL stat
2cf10 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66  ement, it must f
2cf20 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
2cf30 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
2cf40 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
2cf50 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
2cf60 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69  routines.  Or, i
2cf70 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2cf80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2cf90 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72   are constructor
2cfa0 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  s for the [prepa
2cfb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2cfc0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  bject..**.** The
2cfd0 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69   preferred routi
2cfe0 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71  ne to use is [sq
2cff0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d000 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ()].  The.** [sq
2d010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2d020 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65   interface is le
2d030 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20  gacy and should 
2d040 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b  be avoided..** [
2d050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d060 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74  v3()] has an ext
2d070 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f  ra "prepFlags" o
2d080 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73  ption that is us
2d090 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61  ed.** for specia
2d0a0 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  l purposes..**.*
2d0b0 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65  * The use of the
2d0c0 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2d0d0 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20  s is preferred, 
2d0e0 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e  as SQLite curren
2d0f0 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20  tly.** does all 
2d100 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54  parsing using UT
2d110 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36  F-8.  The UTF-16
2d120 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2d130 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61  provided.** as a
2d140 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54   convenience.  T
2d150 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2d160 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e  aces work by con
2d170 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69  verting the.** i
2d180 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55  nput text into U
2d190 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  TF-8, then invok
2d1a0 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ing the correspo
2d1b0 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65  nding UTF-8 inte
2d1c0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
2d1d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
2d1e0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
2d1f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d200 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
2d210 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
2d220 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2d230 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2d240 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d250 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2d260 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
2d270 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d280 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
2d290 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
2d2a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
2d2b0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
2d2c0 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
2d2d0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2d2e0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
2d2f0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
2d300 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
2d310 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d320 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2d330 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  are_v2(),.** and
2d340 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d350 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v3().** interfa
2d360 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2d370 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2d380 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f  re16(), sqlite3_
2d390 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a  prepare16_v2(),.
2d3a0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  ** and sqlite3_p
2d3b0 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73  repare16_v3() us
2d3c0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
2d3d0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
2d3e0 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
2d3f0 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
2d400 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
2d410 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
2d420 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
2d430 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
2d440 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
2d450 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2d460 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
2d470 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
2d480 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
2d490 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d4a0 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
2d4b0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
2d4c0 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
2d4d0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
2d4e0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
2d4f0 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
2d500 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
2d510 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
2d520 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
2d530 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
2d540 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
2d550 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d560 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
2d570 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
2d580 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
2d590 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
2d5a0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
2d5b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2d5c0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
2d5d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
2d5e0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
2d5f0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
2d600 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
2d610 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
2d620 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
2d630 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
2d640 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
2d650 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
2d660 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
2d670 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
2d680 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
2d690 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
2d6a0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
2d6b0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
2d6c0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
2d6d0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
2d6e0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
2d6f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2d700 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
2d710 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2d720 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
2d730 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
2d740 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
2d750 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
2d760 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
2d770 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
2d780 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2d790 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2d7a0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2d7b0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2d7c0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2d7d0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2d7e0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2d7f0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2d800 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2d810 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2d820 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2d830 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2d840 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2d850 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2d860 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2d870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2d880 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2d890 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2d8a0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2d8b0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2d8c0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2d8d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2d8e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d8f0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2d900 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f  e_v3(), sqlite3_
2d910 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a  prepare16_v2(),.
2d920 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  ** and sqlite3_p
2d930 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e  repare16_v3() in
2d940 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63  terfaces are rec
2d950 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
2d960 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a   new programs..*
2d970 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65  * The older inte
2d980 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f  rfaces (sqlite3_
2d990 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
2d9a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d9b0 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e  )).** are retain
2d9c0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2d9d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2d9e0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2d9f0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2da00 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e   ^In the "vX" in
2da10 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2da20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da30 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2da40 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2da50 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2da60 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2da70 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2da80 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2da90 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2daa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2dab0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2dac0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2dad0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2dae0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2daf0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2db00 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2db10 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2db20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2db30 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2db40 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2db50 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2db60 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2db70 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2db80 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2db90 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2dba0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2dbb0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2dbc0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2dbd0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2dbe0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2dbf0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2dc00 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2dc10 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2dc20 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2dc30 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2dc40 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2dc50 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2dc60 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2dc70 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2dc80 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2dc90 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2dca0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2dcb0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2dcc0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2dcd0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2dce0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2dcf0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2dd00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2dd10 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2dd20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2dd30 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2dd40 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2dd50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2dd60 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2dd70 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2dd80 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2dd90 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2dda0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2ddb0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2ddc0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2ddd0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2dde0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2ddf0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2de00 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2de10 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2de20 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2de30 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2de40 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2de50 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2de60 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2de70 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2de80 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2de90 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2dea0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2deb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2dec0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2ded0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2dee0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2def0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2df00 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2df10 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2df20 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2df30 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2df40 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2df50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2df60 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2df70 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2df80 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2df90 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2dfa0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2dfb0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2dfc0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2dfd0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2dfe0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2dff0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2e000 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2e010 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2e020 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2e030 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2e040 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2e050 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2e060 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2e070 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2e080 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2e090 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2e0a0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2e0b0 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c  l>.**.** <p>^sql
2e0c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2e0d0 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73  ) differs from s
2e0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e0f0 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69  2() only in havi
2e100 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20  ng.** the extra 
2e110 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2e120 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20  ter, which is a 
2e130 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73  bit array consis
2e140 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a  ting of zero or.
2e150 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
2e160 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2e170 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45  ERSISTENT|SQLITE
2e180 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67  _PREPARE_*] flag
2e190 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  s.  ^The.** sqli
2e1a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2e1b0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
2e1c0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2e1d0 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
2e1e0 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74  prepare_v3() wit
2e1f0 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61  h a zero prepFla
2e200 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f  gs parameter..*/
2e210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2e220 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
2e230 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2e240 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2e250 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2e260 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2e270 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2e280 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2e290 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2e2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e2b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2e2c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2e2d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2e2e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2e2f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2e300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e310 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2e320 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2e330 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2e340 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2e350 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e360 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
2e370 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e380 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2e390 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2e3a0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2e3b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2e3c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2e3d0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2e3e0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2e3f0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2e400 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2e410 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2e420 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2e430 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2e440 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2e450 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2e460 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2e470 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2e480 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2e490 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2e4a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2e4b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e4c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2e4d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2e4e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2e4f0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2e500 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2e510 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2e520 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2e530 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2e540 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2e550 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2e560 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70    unsigned int p
2e570 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72  repFlags, /* Zer
2e580 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45  o or more SQLITE
2e590 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20  _PREPARE_ flags 
2e5a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2e5b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2e5c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2e5d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2e5e0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2e5f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2e600 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2e610 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2e620 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2e630 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
2e640 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2e650 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2e660 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e670 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2e680 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2e690 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2e6a0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2e6b0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2e6c0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2e6d0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2e6e0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2e6f0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2e700 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2e710 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2e720 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2e730 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2e740 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2e750 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2e760 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2e770 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e780 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2e790 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2e7a0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2e7b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e7c0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2e7d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2e7e0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2e7f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2e800 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2e810 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2e820 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2e830 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2e840 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2e850 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2e860 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2e870 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2e880 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2e890 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2e8a0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2e8b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2e8c0 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71  epare16_v3(.  sq
2e8d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e8e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2e8f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2e900 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2e910 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2e920 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2e930 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2e940 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2e950 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2e960 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2e970 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2e980 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2e990 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2e9a0 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2e9b0 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2e9c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2e9d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2e9e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2e9f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2ea00 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2ea10 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2ea20 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ea30 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2ea40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2ea50 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2ea60 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2ea70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ea80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ea90 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2eaa0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2eab0 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2eac0 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2ead0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2eae0 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2eaf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2eb00 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2eb10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
2eb20 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2eb30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2eb40 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  3()],.** [sqlite
2eb50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2eb60 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ], or [sqlite3_p
2eb70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
2eb80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb90 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20  expanded_sql(P) 
2eba0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ebb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2ebc0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
2ebd0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2ebe0 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70  SQL text of prep
2ebf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2ec00 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20   with.** [bound 
2ec10 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61  parameters] expa
2ec20 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nded..** ^The sq
2ec30 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64  lite3_normalized
2ec40 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2ec50 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2ec60 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a  ter to a UTF-8.*
2ec70 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
2ec80 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61 6c 69 7a  ing the normaliz
2ec90 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  ed SQL text of p
2eca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ecb0 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20 73 65 6d  t P.  The.** sem
2ecc0 61 6e 74 69 63 73 20 75 73 65 64 20 74 6f 20 6e  antics used to n
2ecd0 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51 4c 20 73  ormalize a SQL s
2ece0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 75 6e 73  tatement are uns
2ecf0 70 65 63 69 66 69 65 64 20 61 6e 64 20 73 75 62  pecified and sub
2ed00 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67  ject.** to chang
2ed10 65 2e 20 20 41 74 20 61 20 6d 69 6e 69 6d 75 6d  e.  At a minimum
2ed20 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c 75 65 73  , literal values
2ed30 20 77 69 6c 6c 20 62 65 20 72 65 70 6c 61 63 65   will be replace
2ed40 64 20 77 69 74 68 20 73 75 69 74 61 62 6c 65 0a  d with suitable.
2ed50 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 2e  ** placeholders.
2ed60 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2ed70 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61  mple, if a prepa
2ed80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2ed90 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
2eda0 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22  he SQL.** text "
2edb0 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a  SELECT $abc,:xyz
2edc0 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74  " and if paramet
2edd0 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64  er $abc is bound
2ede0 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35   to integer 2345
2edf0 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65  .** and paramete
2ee00 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e  r :xyz is unboun
2ee10 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2ee20 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72  sql() will retur
2ee30 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  n.** the origina
2ee40 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43  l string, "SELEC
2ee50 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74  T $abc,:xyz" but
2ee60 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2ee70 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20  d_sql().** will 
2ee80 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32  return "SELECT 2
2ee90 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a  345,NULL".)^.**.
2eea0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eeb0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69  expanded_sql() i
2eec0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2eed0 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
2eee0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cient memory.** 
2eef0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20  is available to 
2ef00 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c  hold the result,
2ef10 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c   or if the resul
2ef20 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
2ef30 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75  he.** the maximu
2ef40 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20  m string length 
2ef50 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2ef60 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  e [SQLITE_LIMIT_
2ef70 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LENGTH]..**.** ^
2ef80 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
2ef90 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
2efa0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2efb0 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a  n limits the siz
2efc0 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61  e of.** bound pa
2efd0 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f  rameter expansio
2efe0 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ns.  ^The [SQLIT
2eff0 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f  E_OMIT_TRACE] co
2f000 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
2f010 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69  tion causes sqli
2f020 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2f030 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74  () to always ret
2f040 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  urn NULL..**.** 
2f050 5e 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74  ^The strings ret
2f060 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f070 5f 73 71 6c 28 50 29 20 61 6e 64 20 73 71 6c 69  _sql(P) and sqli
2f080 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73  te3_normalized_s
2f090 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20 6d 61 6e  ql(P).** are man
2f0a0 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2f0b0 6e 64 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  nd are automatic
2f0c0 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20  ally freed when 
2f0d0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
2f0e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2f0f0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2f100 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2f110 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2f120 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2f130 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2f140 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2f150 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f160 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2f170 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2f180 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2f190 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2f1a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2f1b0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2f1c0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2f1d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f1e0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2f1f0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2f200 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f210 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2f220 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64  lite3_normalized
2f230 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2f240 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2f250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2f260 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2f270 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2f280 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2f290 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f2a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f2b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2f2c0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
2f2d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2f2e0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
2f2f0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
2f300 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f310 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
2f320 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
2f330 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
2f340 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2f350 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
2f360 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
2f370 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f380 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
2f390 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
2f3a0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
2f3b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
2f3c0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
2f3d0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
2f3e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2f3f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2f400 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
2f410 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
2f420 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
2f430 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
2f440 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
2f450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
2f460 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
2f470 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2f480 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
2f490 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
2f4a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2f4b0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
2f4c0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
2f4d0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
2f4e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2f4f0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
2f500 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
2f510 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
2f520 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2f530 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
2f540 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
2f550 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f560 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
2f570 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
2f580 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
2f590 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
2f5a0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
2f5b0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
2f5c0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
2f5d0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
2f5e0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
2f5f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2f600 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2f610 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
2f620 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
2f630 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
2f640 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
2f650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
2f660 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
2f670 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
2f680 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
2f690 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
2f6a0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
2f6b0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
2f6c0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
2f6d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
2f6e0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
2f6f0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f700 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2f710 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
2f720 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
2f730 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
2f740 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
2f750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f760 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
2f770 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
2f780 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
2f790 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2f7a0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
2f7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f7c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2f7d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f7e0 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47  ns true for [BEG
2f7f0 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45  IN] since.** [BE
2f800 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73  GIN] merely sets
2f810 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c   internal flags,
2f820 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c   but the [BEGIN|
2f830 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d  BEGIN IMMEDIATE]
2f840 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42   and.** [BEGIN|B
2f850 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20  EGIN EXCLUSIVE] 
2f860 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63  commands do touc
2f870 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  h the database a
2f880 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nd so.** sqlite3
2f890 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2f8a0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66   returns false f
2f8b0 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64  or those command
2f8c0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2f8d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2f8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f8f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f900 49 33 52 45 46 3a 20 51 75 65 72 79 20 54 68 65  I3REF: Query The
2f910 20 45 58 50 4c 41 49 4e 20 53 65 74 74 69 6e 67   EXPLAIN Setting
2f920 20 46 6f 72 20 41 20 50 72 65 70 61 72 65 64 20   For A Prepared 
2f930 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2f940 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f950 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f960 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c  ite3_stmt_isexpl
2f970 61 69 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65  ain(S) interface
2f980 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68   returns 1 if th
2f990 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
2f9a0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20  atement S is an 
2f9b0 45 58 50 4c 41 49 4e 20 73 74 61 74 65 6d 65 6e  EXPLAIN statemen
2f9c0 74 2c 20 6f 72 20 32 20 69 66 20 74 68 65 0a 2a  t, or 2 if the.*
2f9d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  * statement S is
2f9e0 20 61 6e 20 45 58 50 4c 41 49 4e 20 51 55 45 52   an EXPLAIN QUER
2f9f0 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e 54 68 65 20  Y PLAN..** ^The 
2fa00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65  sqlite3_stmt_ise
2fa10 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 66  xplain(S) interf
2fa20 61 63 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ace returns 0 if
2fa30 20 53 20 69 73 0a 2a 2a 20 61 6e 20 6f 72 64 69   S is.** an ordi
2fa40 6e 61 72 79 20 73 74 61 74 65 6d 65 6e 74 20 6f  nary statement o
2fa50 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
2fa60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2fa70 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28  _stmt_isexplain(
2fa80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2fa90 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2faa0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2fab0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2fac0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2fad0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2fae0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2faf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fb00 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2fb10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fb20 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2fb30 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2fb40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fb50 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2fb60 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2fb70 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2fb80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2fb90 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2fba0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2fbb0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2fbc0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2fbd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2fbe0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2fbf0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2fc00 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2fc10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2fc20 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2fc30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2fc40 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2fc50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2fc60 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2fc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2fc80 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2fc90 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2fca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fcb0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2fcc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2fcd0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2fce0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2fcf0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2fd00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2fd10 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2fd20 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2fd30 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2fd40 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2fd50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2fd60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2fd70 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2fd80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2fd90 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2fda0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2fdb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2fdc0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2fdd0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2fde0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2fdf0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2fe00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2fe10 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2fe20 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2fe30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fe40 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
2fe50 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2fe60 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
2fe70 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
2fe80 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
2fe90 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
2fea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2feb0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
2fec0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
2fed0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2fee0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2fef0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
2ff00 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
2ff10 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
2ff20 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
2ff30 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
2ff40 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
2ff50 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
2ff60 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
2ff70 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2ff80 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2ff90 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2ffa0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2ffb0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2ffc0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2ffd0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2ffe0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2fff0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
30000 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
30010 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
30020 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
30030 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
30040 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
30050 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
30060 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
30070 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
30080 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
30090 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
300a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
300b0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
300c0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
300d0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
300e0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
300f0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
30100 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
30110 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
30120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
30130 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
30140 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e  _value_dup()] in
30150 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
30160 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74  sed to construct
30170 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65   a new .** prote
30180 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30190 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f  ue from an unpro
301a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
301b0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
301c0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
301d0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
301e0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
301f0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
30200 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
30210 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
30220 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
30230 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
30240 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30250 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
30260 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
30270 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
30280 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30290 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
302a0 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
302b0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
302c0 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
302d0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
302e0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
302f0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
30300 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
30310 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
30320 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
30330 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
30340 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
30350 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
30360 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
30370 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
30380 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
30390 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
303a0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
303b0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
303c0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
303d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
303e0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
303f0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
30400 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
30410 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
30420 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
30430 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
30440 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
30450 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
30460 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
30470 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
30480 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
30490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
304a0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
304b0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
304c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
304d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
304e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
304f0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
30500 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
30510 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
30520 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
30530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30540 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
30550 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
30560 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
30570 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
30580 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
30590 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
305a0 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
305b0 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
305c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
305d0 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
305e0 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e   used as argumen
305f0 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ts.** to [sqlite
30600 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30610 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ], [sqlite3_bind
30620 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a  _value()], and.*
30630 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30640 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  _dup()]..** The 
30650 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30660 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
30670 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
30680 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
30690 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
306a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
306b0 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
306c0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
306d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c  qlite3_value sql
306e0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
306f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
30700 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
30710 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
30720 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
30730 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
30740 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
30750 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
30760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
30770 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
30780 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
30790 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
307a0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
307b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
307c0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
307d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
307e0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
307f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
30810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
30820 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
30830 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
30840 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
30850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
30860 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
30870 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
30880 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30890 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
308a0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
308b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
308c0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
308d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
308e0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
308f0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
30900 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
30910 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
30930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
30940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30950 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
30960 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
30970 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
30980 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
30990 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
309a0 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
309b0 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
309c0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
309d0 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
309e0 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
309f0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
30a00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30a10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
30a20 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
30a30 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
30a40 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
30a50 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
30a60 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
30a70 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
30a80 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
30a90 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
30aa0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
30ab0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
30ac0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
30ad0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
30ae0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
30af0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
30b00 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
30b10 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
30b20 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
30b30 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
30b40 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
30b50 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
30b60 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
30b70 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
30b80 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
30b90 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
30ba0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
30bb0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
30bc0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
30bd0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
30be0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
30bf0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
30c00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
30c10 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
30c20 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
30c30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
30c40 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
30c50 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
30c60 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
30c70 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
30c80 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
30c90 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
30ca0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
30cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30cc0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
30cd0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
30ce0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
30cf0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
30d00 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
30d10 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
30d20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
30d30 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
30d40 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
30d50 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
30d60 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
30d70 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
30d80 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
30d90 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
30da0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
30db0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
30dc0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
30dd0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
30de0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
30df0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
30e00 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
30e10 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
30e20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30e30 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30e40 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
30e50 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
30e60 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
30e70 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
30e80 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
30e90 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
30ea0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
30eb0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
30ec0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
30ed0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
30ee0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
30ef0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
30f00 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
30f10 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
30f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
30f30 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
30f40 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
30f50 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
30f60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30f70 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
30f80 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
30f90 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
30fa0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
30fb0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
30fc0 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
30fd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
30fe0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
30ff0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
31000 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
31010 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
31020 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
31030 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
31040 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
31050 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
31060 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
31070 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31080 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
31090 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
310a0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
310b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
310c0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
310d0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
310e0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
310f0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
31100 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31110 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
31120 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
31130 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
31140 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
31150 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
31160 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
31170 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
31180 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
31190 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
311a0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
311b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
311c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
311d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
311e0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
311f0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
31200 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31210 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
31220 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
31230 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
31240 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
31250 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
31260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
31270 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
31280 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
31290 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
312a0 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
312b0 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
312c0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
312d0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
312e0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
312f0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
31300 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
31310 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
31320 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
31330 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
31340 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
31350 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
31360 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
31370 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
31380 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
31390 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
313a0 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
313b0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
313c0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
313d0 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
313e0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
313f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
31400 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
31410 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
31420 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
31430 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
31440 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
31450 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
31460 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
31470 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
31480 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
31490 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
314a0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
314b0 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
314c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
314d0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
314e0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
314f0 6f 20 74 68 65 20 62 69 6e 64 20 41 50 49 20 66  o the bind API f
31500 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 65 70 74 20  ails,.** except 
31510 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  the destructor i
31520 73 20 6e 6f 74 20 63 61 6c 6c 65 64 20 69 66 20  s not called if 
31530 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
31540 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a  ter is a NULL.**
31550 20 70 6f 69 6e 74 65 72 20 6f 72 20 74 68 65 20   pointer or the 
31560 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
31570 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
31580 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
31590 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
315a0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
315b0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
315c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
315d0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
315e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
315f0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
31600 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
31610 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
31620 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
31630 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
31640 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
31650 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
31660 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
31670 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
31680 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
31690 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
316a0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
316b0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
316c0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
316d0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
316e0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
316f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
31700 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
31710 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
31720 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
31730 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
31740 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
31750 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
31760 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
31770 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
31780 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
31790 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
317a0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
317b0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
317c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
317d0 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
317e0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
317f0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
31800 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
31810 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
31820 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
31830 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
31840 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
31850 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
31860 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
31870 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
31880 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
31890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
318a0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
318b0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
318c0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
318d0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
318e0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
318f0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
31900 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
31910 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
31920 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
31930 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
31940 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
31950 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
31960 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
31970 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
31980 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
31990 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
319a0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
319b0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
319c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
319d0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
319e0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
319f0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
31a00 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
31a10 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
31a20 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
31a30 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54  h BLOB..**.** ^T
31a40 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
31a50 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c  pointer(S,I,P,T,
31a60 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65  D) routine cause
31a70 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d  s the I-th param
31a80 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70  eter in.** [prep
31a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31aa0 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c  S to have an SQL
31ab0 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20   value of NULL, 
31ac0 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a  but to also be.*
31ad0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
31ae0 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20  h the pointer P 
31af0 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69  of type T.  ^D i
31b00 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
31b10 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20  pointer or.** a 
31b20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
31b30 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
31b40 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20   for P. ^SQLite 
31b50 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a  will invoke the.
31b60 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  ** destructor D 
31b70 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
31b80 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e  gument of P when
31b90 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20   it is finished 
31ba0 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65  using.** P.  The
31bb0 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f   T parameter sho
31bc0 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20  uld be a static 
31bd0 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62  string, preferab
31be0 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c  ly a string.** l
31bf0 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69  iteral. The sqli
31c00 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
31c10 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  () routine is pa
31c20 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f  rt of the.** [po
31c30 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
31c40 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
31c50 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
31c60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
31c70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
31c80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
31c90 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
31ca0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
31cb0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
31cc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31cd0 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
31ce0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
31cf0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
31d00 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
31d10 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
31d20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
31d30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
31d40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
31d50 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
31d60 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31d70 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
31d80 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
31d90 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
31da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31db0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
31dc0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
31dd0 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
31de0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
31df0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
31e00 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
31e10 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
31e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
31e30 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
31e40 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
31e50 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
31e60 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
31e70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31e80 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
31e90 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
31ea0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
31eb0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
31ec0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
31ed0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
31ee0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
31ef0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
31f00 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
31f10 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
31f20 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
31f30 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
31f40 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
31f50 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
31f60 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
31f70 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
31f80 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
31f90 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
31fa0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
31fb0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
31fc0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
31fd0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
31fe0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
31ff0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
32000 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
32010 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32020 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
32030 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
32040 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
32050 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
32060 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
32070 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
32080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32090 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
320a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
320b0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
320c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
320d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
320e0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
320f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
32100 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
32110 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
32120 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
32130 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
32140 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
32150 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
32160 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
32170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32180 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
32190 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
321a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
321b0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
321c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
321d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
321e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
321f0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
32200 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
32210 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
32220 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
32230 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
32240 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32250 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32260 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
32270 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
32280 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
32290 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
322a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
322b0 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
322c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
322d0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
322e0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
322f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32300 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
32310 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
32320 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
32330 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
32340 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32350 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
32360 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
32380 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
32390 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
323a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64  const char*,void
323b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
323c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
323d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
323e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
323f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
32400 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
32410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32420 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
32430 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
32440 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
32450 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
32460 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
32470 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
32480 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
32490 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
324a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
324b0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
324c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
324d0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
324e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
324f0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
32500 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
32510 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
32520 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
32530 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
32540 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
32550 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
32560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32570 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
32580 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
32590 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
325a0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
325b0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
325c0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
325d0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
325e0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
325f0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
32600 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
32610 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
32620 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
32630 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
32640 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
32650 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
32660 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
32670 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
32680 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
32690 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
326a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
326b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
326c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
326d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
326e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
326f0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
32700 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32710 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
32720 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
32730 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
32740 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
32750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32760 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
32770 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
32780 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32790 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
327a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
327b0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
327c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
327d0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
327e0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
327f0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
32800 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32810 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
32820 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
32830 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
32840 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
32850 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
32860 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
32870 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
32880 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
32890 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
328a0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
328b0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
328c0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
328d0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
328e0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
328f0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
32900 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
32910 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
32920 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
32930 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
32940 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
32950 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
32960 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
32970 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
32980 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
32990 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
329a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
329b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
329c0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
329d0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
329e0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
329f0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
32a00 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
32a10 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
32a20 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
32a30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
32a40 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
32a50 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
32a60 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
32a70 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
32a80 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
32a90 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
32aa0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
32ab0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
32ac0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
32ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32ae0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
32af0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32b00 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
32b10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
32b20 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
32b30 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
32b40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32b50 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
32b60 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
32b70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
32b80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
32b90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32ba0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
32bb0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32bc0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
32bd0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
32be0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
32bf0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
32c00 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
32c10 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
32c20 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
32c30 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
32c40 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
32c50 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
32c60 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
32c70 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
32c80 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
32c90 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
32ca0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
32cb0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
32cc0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
32cd0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
32ce0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
32cf0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
32d00 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
32d10 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
32d20 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
32d30 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
32d40 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
32d50 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
32d60 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
32d70 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
32d80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
32d90 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
32da0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
32db0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
32dc0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
32dd0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
32de0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
32df0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32e00 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
32e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
32e20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
32e30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
32e40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32e50 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
32e60 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
32e70 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
32e80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
32e90 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
32ea0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
32eb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
32ec0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32ed0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
32ee0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
32ef0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
32f00 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
32f10 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
32f20 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
32f30 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
32f40 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
32f50 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
32f60 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
32f70 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
32f80 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
32f90 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
32fa0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
32fb0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
32fc0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32fd0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
32fe0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
32ff0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
33000 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33010 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
33020 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
33030 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
33040 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
33050 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
33060 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
33070 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
33080 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
33090 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
330a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
330b0 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
330c0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
330d0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
330e0 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
330f0 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
33100 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
33110 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
33120 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
33130 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
33140 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
33150 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
33160 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
33170 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
33180 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
33190 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
331a0 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
331b0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
331c0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
331d0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
331e0 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
331f0 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
33200 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
33210 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
33220 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33230 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
33240 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
33250 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
33260 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
33270 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
33280 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
33290 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
332a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
332b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
332c0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
332d0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
332e0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
332f0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
33300 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
33310 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
33320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
33330 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
33340 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
33350 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
33360 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
33370 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
33380 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33390 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
333a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
333b0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
333c0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
333d0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
333e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
333f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33400 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
33410 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
33420 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
33430 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
33440 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
33450 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
33460 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
33470 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
33480 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
33490 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
334a0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
334b0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
334c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
334d0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
334e0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
334f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
33500 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
33510 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
33520 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
33530 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
33540 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33550 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
33560 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
33570 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
33580 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
33590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
335a0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
335b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
335c0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
335d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
335e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
335f0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
33600 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
33610 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
33620 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
33630 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
33640 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
33650 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
33660 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
33670 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
33680 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
33690 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
336a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
336b0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
336c0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
336d0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
336e0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
336f0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
33700 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
33710 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
33720 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
33730 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
33740 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
33750 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
33760 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
33770 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
33790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
337a0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
337b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
337c0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
337d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
337e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
337f0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
33800 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
33810 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33820 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33830 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
33840 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
33850 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
33860 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
33870 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
33880 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
33890 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
338a0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
338b0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
338c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
338d0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
338e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
338f0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
33900 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
33910 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
33920 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
33930 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
33940 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
33950 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
33960 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
33970 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
33980 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
33990 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
339a0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
339b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
339c0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
339d0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
339e0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
339f0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
33a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
33a10 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
33a20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
33a30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
33a40 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
33a50 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
33a60 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
33a70 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
33a80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33a90 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
33aa0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
33ab0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
33ac0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
33ad0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
33ae0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
33af0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
33b00 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
33b10 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
33b20 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
33b30 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
33b40 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
33b50 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
33b60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
33b70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
33b80 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
33b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33ba0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
33bb0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
33bc0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
33bd0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
33be0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
33bf0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
33c00 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
33c10 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
33c20 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
33c30 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
33c40 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
33c50 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
33c60 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
33c70 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
33c80 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
33c90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
33ca0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
33cb0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
33cc0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
33cd0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
33ce0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
33cf0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
33d00 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
33d10 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
33d20 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
33d30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
33d40 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
33d50 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
33d60 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
33d70 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
33d80 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
33d90 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
33da0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
33db0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
33dc0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
33dd0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
33de0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
33df0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
33e00 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
33e10 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
33e20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
33e30 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
33e40 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
33e50 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
33e60 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
33e70 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
33e80 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
33e90 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
33ea0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
33eb0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
33ec0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
33ed0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
33ee0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
33ef0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
33f00 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
33f10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33f20 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
33f30 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
33f40 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
33f50 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
33f60 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
33f70 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
33f80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
33f90 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
33fa0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
33fb0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
33fc0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
33fd0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
33fe0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
33ff0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
34000 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
34010 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
34020 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
34030 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
34040 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34050 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34060 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
34070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
34080 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
34090 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
340a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
340b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
340c0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
340d0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
340e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
340f0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
34100 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
34110 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
34120 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
34130 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
34140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
34150 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
34160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
34170 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
34180 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
34190 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
341a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
341b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
341c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
341d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
341e0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
341f0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
34200 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34210 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
34220 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
34230 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
34240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
34250 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
34260 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
34270 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
34280 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
34290 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
342a0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
342b0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
342c0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
342d0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
342e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
342f0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
34300 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
34310 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
34320 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
34330 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
34340 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
34350 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
34360 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
34370 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
34380 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
34390 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
343a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
343b0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
343c0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
343d0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
343e0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
343f0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
34400 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
34410 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
34420 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
34430 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
34440 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
34450 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
34460 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
34470 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
34480 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
34490 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
344a0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
344b0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
344c0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
344d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
344e0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
344f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
34500 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
34510 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
34520 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
34530 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
34540 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
34550 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
34560 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
34570 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
34580 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
34590 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
345a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
345b0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
345c0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
345d0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
345e0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
345f0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
34600 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
34610 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
34620 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
34630 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
34640 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
34650 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
34660 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
34670 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
34680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
34690 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
346a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
346b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
346c0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
346d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
346e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
346f0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
34700 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
34710 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34720 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
34730 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
34740 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
34750 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
34760 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
34770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34780 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
34790 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
347a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
347b0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
347c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
347d0 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
347e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
347f0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
34800 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
34810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34820 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
34830 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
34840 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
34850 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
34860 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
34870 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
34880 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
34890 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
348a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
348b0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
348c0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
348d0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
348e0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
348f0 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
34900 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
34910 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
34920 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
34930 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
34940 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
34950 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
34960 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
34970 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
34980 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
34990 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
349a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
349b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
349c0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
349d0 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
349e0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
349f0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
34a00 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
34a10 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
34a20 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
34a30 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
34a40 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
34a50 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
34a60 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
34a70 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
34a80 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
34a90 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
34aa0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
34ab0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
34ac0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
34ad0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
34ae0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
34af0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
34b00 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
34b10 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
34b20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
34b30 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
34b40 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
34b50 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
34b60 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
34b70 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
34b80 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
34b90 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
34ba0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
34bb0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
34bc0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
34bd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
34be0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
34bf0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
34c00 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
34c10 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
34c20 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
34c30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
34c40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
34c50 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
34c60 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
34c70 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
34c80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
34c90 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
34ca0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
34cb0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
34cc0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
34cd0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
34ce0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
34cf0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
34d00 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
34d10 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
34d20 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
34d30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
34d40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
34d50 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
34d60 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
34d70 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
34d80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34d90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
34da0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
34db0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
34dc0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
34dd0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
34de0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
34df0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
34e00 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
34e10 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
34e20 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
34e30 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
34e40 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
34e50 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
34e60 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
34e70 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
34e80 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
34e90 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
34ea0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
34eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
34ec0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
34ed0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
34ee0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
34ef0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
34f00 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
34f10 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
34f20 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
34f30 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
34f40 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
34f50 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
34f60 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
34f70 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
34f80 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
34f90 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
34fa0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
34fb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
34fc0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
34fd0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
34fe0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
34ff0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
35000 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
35010 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
35020 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
35030 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
35040 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
35050 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
35060 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
35070 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
35080 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35090 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
350a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
350b0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
350c0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
350d0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
350e0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
350f0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
35100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
35110 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
35120 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
35130 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
35140 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
35150 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
35160 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
35170 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
35180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35190 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
351a0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
351b0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
351c0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
351d0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
351e0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
351f0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
35200 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
35210 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
35220 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
35230 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
35240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35250 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
35260 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
35270 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
35280 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
35290 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
352a0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
352b0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
352c0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
352d0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
352e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
352f0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
35300 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
35310 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
35320 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
35330 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
35340 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
35350 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
35360 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
35370 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
35380 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
35390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
353a0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
353b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
353c0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
353d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
353e0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
353f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
35400 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
35410 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
35420 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
35430 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
35440 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
35450 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
35460 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
35470 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
35480 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
35490 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
354a0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
354b0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
354c0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
354d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
354e0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
354f0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
35500 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
35510 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
35520 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
35530 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
35540 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
35550 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
35560 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
35570 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
35580 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
35590 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
355a0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
355b0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
355c0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
355d0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
355e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
355f0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
35600 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
35610 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
35620 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
35630 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
35640 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
35650 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
35660 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
35670 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
35680 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
35690 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
356a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
356b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
356c0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
356d0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
356e0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
356f0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
35700 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
35710 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
35720 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
35730 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
35740 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
35750 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
35760 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
35770 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
35780 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
35790 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
357a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
357b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
357c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
357d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
357e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
357f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35800 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
35810 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
35820 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
35830 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
35840 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
35850 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
35860 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
35870 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
35880 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
35890 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
358a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
358b0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
358c0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
358d0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
358e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
358f0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
35900 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35910 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
35920 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
35930 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
35940 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
35950 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35960 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
35970 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35990 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
359a0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
359b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
359c0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
359d0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
359e0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
359f0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
35a00 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
35a10 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
35a20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
35a30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
35a40 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
35a50 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
35a60 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
35a70 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
35a80 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
35a90 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
35aa0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
35ab0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
35ac0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
35ad0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35af0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
35b00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
35b10 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
35b20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
35b30 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
35b40 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
35b50 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
35b60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
35b70 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
35b80 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
35b90 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
35ba0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
35bb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
35bc0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
35bd0 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
35be0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
35bf0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
35c00 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
35c10 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
35c20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
35c30 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
35c40 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
35c50 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
35c60 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
35c70 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
35c80 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
35c90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35ca0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
35cb0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
35cc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35cd0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
35ce0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
35cf0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
35d00 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
35d10 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
35d20 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
35d30 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
35d40 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
35d50 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
35d60 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
35d70 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
35d80 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
35d90 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
35da0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
35db0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
35dc0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
35dd0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
35de0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
35df0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
35e00 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
35e10 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
35e20 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
35e30 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
35e40 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
35e50 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
35e60 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
35e70 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
35e80 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
35e90 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
35ea0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
35eb0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
35ec0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
35ed0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
35ee0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
35ef0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35f00 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
35f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
35f20 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
35f30 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
35f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35f50 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
35f60 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
35f70 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
35f80 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
35f90 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
35fa0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
35fb0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
35fc0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
35fd0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
35fe0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
35ff0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
36000 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
36010 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
36020 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
36030 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
36040 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
36050 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
36060 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
36070 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
36080 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
36090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
360a0 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
360b0 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
360c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
360d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
360e0 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
360f0 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
36100 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
36110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
36120 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
36130 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
36140 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
36150 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36160 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
36170 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
36180 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
36190 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
361a0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
361b0 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
361c0 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
361d0 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
361e0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
361f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
36200 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
36210 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
36220 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
36230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
36240 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
36250 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
36260 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
36270 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
36280 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36290 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
362a0 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
362b0 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
362c0 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
362d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
362e0 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
362f0 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
36300 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
36310 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
36320 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
36330 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36340 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
36350 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
36360 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
36370 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
36380 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
36390 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
363a0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
363b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
363c0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
363d0 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
363e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
363f0 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
36400 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
36410 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
36420 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
36430 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
36440 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
36450 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
36460 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
36470 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
36480 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
36490 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
364a0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
364b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
364c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
364d0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
364e0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
364f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
36500 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
36510 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
36520 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
36530 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
36540 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
36550 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
36560 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
36570 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
36580 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
36590 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
365a0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
365b0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
365c0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
365d0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
365e0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
365f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
36600 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
36610 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
36620 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
36630 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
36640 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
36650 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
36660 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
36670 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
36680 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
36690 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
366a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
366b0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
366c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
366d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
366e0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
366f0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
36700 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
36710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36720 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
36730 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
36740 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
36750 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
36760 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
36770 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
36780 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
36790 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
367a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
367b0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
367c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
367d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
367e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
367f0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
36800 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
36810 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
36820 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
36830 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
36840 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
36850 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
36860 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
36870 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
36880 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
36890 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
368a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
368b0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
368c0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
368d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
368e0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
368f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
36900 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
36910 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
36920 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
36930 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
36940 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
36950 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
36960 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
36970 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
36980 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
36990 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
369a0 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
369b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
369c0 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
369d0 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
369e0 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
369f0 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
36a00 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
36a10 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
36a20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36a30 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
36a40 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
36a50 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
36a60 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
36a70 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
36a80 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
36a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
36ab0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
36ac0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
36ad0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
36ae0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
36af0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
36b00 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
36b10 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
36b20 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
36b30 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
36b40 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
36b50 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
36b60 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
36b70 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
36b80 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
36b90 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
36ba0 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
36bb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
36bc0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
36bd0 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
36be0 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
36bf0 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
36c00 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
36c10 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
36c20 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
36c30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
36c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
36c50 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
36c60 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
36c70 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
36c80 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
36c90 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
36ca0 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
36cb0 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
36cc0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
36cd0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
36ce0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
36cf0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
36d00 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
36d10 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
36d20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
36d30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
36d40 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
36d50 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
36d60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
36d70 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
36d80 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
36d90 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
36da0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
36db0 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
36dc0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
36dd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
36de0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
36df0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
36e00 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
36e10 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
36e20 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
36e30 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
36e40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
36e50 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
36e60 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
36e70 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
36e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36e90 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
36ea0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
36eb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
36ec0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
36ed0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
36ee0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
36ef0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
36f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36f10 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
36f20 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
36f30 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
36f40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
36f50 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
36f60 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
36f70 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
36f80 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
36f90 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
36fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
36fb0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
36fc0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
36fd0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
36fe0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
36ff0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37000 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
37010 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
37020 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
37030 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37040 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
37050 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
37060 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
37070 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
37080 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
37090 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
370a0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
370b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
370c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
370d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
370e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
370f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
37100 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
37110 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37120 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
37130 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
37140 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
37150 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
37160 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37170 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
37180 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
37190 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
371a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
371b0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
371c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
371d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
371e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
371f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
37200 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
37210 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
37220 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
37230 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
37240 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
37250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37260 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
37270 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
37280 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
37290 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
372a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
372b0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
372c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
372d0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
372e0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
372f0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
37300 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
37310 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
37320 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
37330 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
37340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37350 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
37360 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37370 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
37380 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
37390 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
373a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
373b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
373c0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
373d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
373e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
373f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37400 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
37410 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
37420 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
37430 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
37440 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
37450 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
37460 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
37470 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
37480 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
37490 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
374a0 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
374b0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
374c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
374d0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
374e0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
374f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37500 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
37510 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
37520 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
37530 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
37540 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
37550 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
37560 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
37570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
37580 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
37590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
375a0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
375b0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
375c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
375d0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
375e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
375f0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
37600 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
37610 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
37620 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
37630 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
37640 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
37650 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
37660 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
37670 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
37680 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
37690 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
376a0 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
376b0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
376c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
376d0 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
376e0 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
376f0 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
37700 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37710 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
37720 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37730 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
37740 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
37750 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
37760 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
37770 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
37780 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
37790 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
377a0 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
377b0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
377c0 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
377d0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
377e0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
377f0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
37800 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
37810 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
37820 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
37830 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
37840 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
37850 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
37860 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
37870 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
37880 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
37890 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
378a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
378b0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
378c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
378d0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
378e0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
378f0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
37900 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
37910 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
37920 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
37930 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
37940 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
37950 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
37960 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
37970 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
37980 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
37990 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
379a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
379b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
379c0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
379d0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
379e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
379f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
37a00 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
37a10 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
37a20 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
37a30 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
37a40 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
37a50 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
37a60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
37a70 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
37a80 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
37a90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
37aa0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
37ab0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
37ac0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
37ad0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
37ae0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
37af0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
37b00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
37b10 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
37b20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
37b30 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
37b40 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
37b50 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
37b60 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
37b70 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
37b80 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
37b90 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
37ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
37bb0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
37bc0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
37bd0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
37be0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
37bf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
37c00 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
37c10 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
37c20 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
37c30 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
37c40 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
37c50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
37c60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
37c70 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
37c80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
37c90 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
37ca0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
37cb0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
37cc0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
37cd0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
37ce0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
37cf0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
37d00 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
37d10 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
37d20 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
37d30 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
37d40 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
37d50 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
37d60 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
37d70 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
37d80 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
37d90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
37da0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
37db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
37dc0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
37dd0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
37de0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
37df0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
37e00 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
37e10 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
37e20 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
37e30 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
37e40 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
37e50 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
37e60 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
37e70 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
37e80 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
37e90 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
37ea0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
37eb0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
37ec0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
37ed0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
37ee0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
37ef0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
37f00 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
37f10 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
37f20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37f30 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
37f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37f50 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
37f60 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
37f70 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
37f80 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
37f90 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
37fa0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
37fb0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
37fc0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
37fd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
37fe0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
37ff0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
38000 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
38010 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
38020 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
38030 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
38040 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
38050 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
38060 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
38070 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
38080 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
38090 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
380a0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
380b0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
380c0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
380d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
380e0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
380f0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
38100 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
38110 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
38120 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
38130 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
38140 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
38150 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
38160 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
38170 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
38180 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
38190 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
381a0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
381b0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
381c0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
381d0 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
381e0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
381f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
38200 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
38210 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
38220 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
38230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
38240 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
38250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
38260 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
38270 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
38280 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
38290 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
382a0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
382b0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
382c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
382d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
382e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
382f0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
38300 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
38310 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
38320 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
38330 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
38340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
38350 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
38360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
38370 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
38380 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
38390 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
383a0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
383b0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
383c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
383d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
383e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
383f0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
38400 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
38410 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
38420 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
38430 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
38440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
38450 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
38460 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
38470 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
38480 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
38490 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
384a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
384b0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
384c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
384d0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
384e0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
384f0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
38500 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
38510 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
38520 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
38530 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
38540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
38550 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
38560 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
38570 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
38580 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
38590 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
385a0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
385b0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
385c0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
385d0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
385e0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
385f0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
38600 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
38610 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
38620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
38630 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
38640 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
38650 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  )]..**.** As lon
38660 67 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 70  g as the input p
38670 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 6f  arameters are co
38680 72 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f 75  rrect, these rou
38690 74 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a  tines will only.
386a0 2a 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f 75  ** fail if an ou
386b0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
386c0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
386d0 61 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73  a format convers
386e0 69 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65  ion..** Only the
386f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65   following subse
38700 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20  t of interfaces 
38710 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 6f  are subject to o
38720 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  ut-of-memory.** 
38730 65 72