/ Hex Artifact Content
Login

Artifact 7fd42ad3247efa14010aae1fb118face5b3a7945b4954c3d6e9b142d15a8a779:


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 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
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 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<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 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<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 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
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 34 3c 3c 38 29 29  _IOERR | (4<<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 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_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 35 3c 3c 38 29 29 0a  IOERR | (5<<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 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
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 36 3c 3c 38 29 29 0a 23  OERR | (6<<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 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
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 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
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 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
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 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67d0: 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54  OPEN_FILEPROTECT
67e0: 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 20  ION_MASK        
67f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30 30           0x00700
6810: 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64  000../* Reserved
6820: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6840: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6850: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6860: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6870: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6880: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6890: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
68a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
68b0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
68c0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
68d0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
68e0: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
68f0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6900: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6910: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6920: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6930: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6940: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6960: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6970: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
69a0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
69b0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
69c0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
69d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
69e0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
69f0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6a00: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6a10: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6a20: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6a30: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6a40: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6a50: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6a60: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6a70: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6a80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a90: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6aa0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6ab0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6ac0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6ad0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6ae0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6af0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6b00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6b10: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6b20: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6b30: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6b40: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6b50: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6b60: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6b70: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6b80: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6b90: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6ba0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6bb0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6bc0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6bd0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6be0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6bf0: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6c00: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6c10: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6c20: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6c30: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6c40: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6c50: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6c60: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6c70: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6c80: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6c90: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6ca0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6cb0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6cc0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6cd0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6ce0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6cf0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6d00: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6d10: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6d20: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6d30: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6d40: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6d50: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6d60: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6d70: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6d80: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6d90: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6da0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6db0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6dc0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6dd0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6de0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6df0: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6e00: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6e10: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6e20: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6e30: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6e40: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6e50: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6e60: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6e70: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6e80: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6e90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6ea0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6eb0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6ec0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ed0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ef0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6f00: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f10: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6f30: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6f40: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6f60: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6f70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f80: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6f90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6fa0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6fb0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6fd0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6fe0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ff0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7020: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7030: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7040: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7050: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7070: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7080: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7090: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
70a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
70b0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
70c0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
70d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
70e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
70f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7100: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7110: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7120: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7130: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7150: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7160: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7170: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7180: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7190: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
71a0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
71b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
71c0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
71d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
71e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
71f0: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7200: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7210: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7220: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7230: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7240: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7250: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7260: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7270: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7280: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
7290: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
72a0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
72b0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
72c0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
72d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
72e0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
72f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7300: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7310: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7320: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7340: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7350: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7360: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7370: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7380: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7390: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
73a0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
73b0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
73c0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
73d0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
73e0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
73f0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7410: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7420: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7430: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7440: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7450: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7460: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7470: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7480: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
7490: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
74a0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
74b0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
74c0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
74d0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
74e0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
74f0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7500: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7510: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7520: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7530: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7540: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7550: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7560: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7570: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7580: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7590: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
75a0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
75b0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
75c0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
75d0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
75e0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
75f0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7600: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7610: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7620: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7630: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7640: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7650: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7660: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7670: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7680: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7690: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
76a0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
76b0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
76c0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
76d0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
76e0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
76f0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7700: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7710: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7720: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7730: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7740: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7750: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7760: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7770: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7780: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7790: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
77a0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
77b0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
77c0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
77d0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
77e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
77f0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7800: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7810: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7820: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7830: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7840: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7850: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7860: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7870: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7880: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7890: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
78a0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
78b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
78d0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
78e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
78f0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7900: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7910: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7920: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7930: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7940: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7950: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7960: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7970: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7980: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7990: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
79a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
79b0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
79c0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
79d0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
79e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
79f0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7a00: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7a10: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7a20: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7a30: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7a40: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7a50: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7a60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7a70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7a80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7a90: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7aa0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7ab0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7ac0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7ad0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7ae0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7af0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7b00: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7b10: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7b20: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7b40: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7b50: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7b60: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7b70: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7b80: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7b90: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7ba0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7bb0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7bc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bd0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7be0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c00: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7c10: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7c20: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7c30: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7c40: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7c50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7c60: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7c70: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7c80: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7c90: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7ca0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7cb0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7cc0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7cd0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7ce0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7cf0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7d00: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7d10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7d20: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7d30: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7d40: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7d50: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7d60: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7d70: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7d80: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7d90: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7da0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7db0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7dc0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7dd0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7de0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7df0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7e00: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7e10: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7e20: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7e30: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7e40: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e50: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7e60: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e70: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7e80: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7e90: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7ea0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7eb0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7ec0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ed0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7ee0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7ef0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7f00: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7f10: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7f20: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7f30: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7f40: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7f50: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7f60: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7f70: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7f80: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7f90: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7fa0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7fb0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7fc0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7fd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7fe0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7ff0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8000: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8010: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8020: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8030: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8040: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8060: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8070: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8080: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
8090: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
80a0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
80b0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
80c0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
80d0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
80e0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
80f0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8100: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8110: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8120: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8130: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8140: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8150: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8160: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8170: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8180: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
8190: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
81a0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
81b0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
81c0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
81d0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
81e0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
81f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8200: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8210: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8220: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8230: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8240: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8250: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8260: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8270: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8280: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8290: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
82a0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
82b0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
82c0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
82d0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
82e0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
82f0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8300: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8310: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8320: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8330: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8340: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8350: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8360: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8370: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8380: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
8390: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
83a0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
83b0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
83c0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
83d0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
83e0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
83f0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8400: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8410: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8420: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8430: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8440: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8450: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8460: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8470: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8480: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
8490: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
84a0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
84b0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
84c0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
84d0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
84e0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
84f0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8500: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8510: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8520: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8530: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8540: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8550: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8560: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8570: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8580: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
8590: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
85a0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
85b0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
85c0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
85d0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
85e0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
85f0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8600: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8610: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8620: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8630: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8640: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8650: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8660: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8670: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8680: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8690: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
86a0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
86b0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
86c0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
86d0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
86e0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
86f0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8700: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8710: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8720: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8730: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8740: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8750: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8770: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8780: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8790: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
87a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87b0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87d0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8800: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8810: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8820: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8830: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8850: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8860: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8870: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8890: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
88a0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
88b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
88c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
88d0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
88f0: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8900: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8910: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8920: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8940: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8950: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8960: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8970: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8980: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8990: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
89a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
89b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
89c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
89d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
89e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
89f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8a00: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8a10: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8a20: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8a40: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8a50: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8a60: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8a70: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8a80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8a90: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8aa0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8ab0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8ac0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8ad0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8ae0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8af0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8b00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8b10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8b20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8b30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8b40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8b50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8b60: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8b70: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8b80: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8b90: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8ba0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8bb0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8bc0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8bd0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8be0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8bf0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c00: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8c10: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8c20: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8c30: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8c40: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8c50: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8c60: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8c70: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8c80: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8c90: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8ca0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8cb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8cc0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8cd0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8ce0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8cf0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8d00: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8d10: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8d20: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8d30: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8d40: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8d50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8d60: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8d70: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8d80: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8d90: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8da0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8db0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8dc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8dd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8de0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8df0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8e00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8e10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8e20: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8e30: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8e40: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8e50: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8e60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8e70: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8e80: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8e90: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8ea0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8eb0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ed0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8ee0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8ef0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8f00: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f10: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8f20: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8f30: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8f40: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8f50: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8f60: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8f70: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8f80: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8f90: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8fa0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8fb0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8fc0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8fd0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8fe0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8ff0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9000: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9010: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9020: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9030: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9040: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9050: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9060: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9070: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9080: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
9090: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
90a0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
90b0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
90c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
90d0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
90e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
90f0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9100: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9110: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9120: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9130: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9140: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9150: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9160: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9170: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9180: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
9190: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
91a0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
91b0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
91c0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
91d0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
91e0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
91f0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9200: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9210: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9220: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9230: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9240: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9260: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9270: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9280: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9290: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
92c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
92d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
92e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
92f0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9300: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9310: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9320: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9330: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9340: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9350: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9360: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9370: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9380: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
9390: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
93a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
93b0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
93c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
93d0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
93e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
93f0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9400: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9410: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9420: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9430: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9440: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9450: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9460: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9470: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9480: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9490: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
94a0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
94b0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
94c0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
94d0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
94e0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
94f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9500: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9510: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9520: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9530: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9540: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9550: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9560: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9570: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9580: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9590: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
95a0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
95b0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
95c0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
95d0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
95e0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
95f0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9600: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9610: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9620: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9630: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9650: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9660: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9670: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9680: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9690: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
96a0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
96b0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
96c0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
96d0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
96e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
96f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9700: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9710: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9720: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9730: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9740: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9750: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9760: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9770: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9780: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9790: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
97a0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
97b0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
97c0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
97d0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
97e0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
97f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9800: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9810: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9820: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9830: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9840: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9850: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9860: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9870: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9880: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9890: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
98a0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
98b0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
98c0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
98d0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
98e0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
98f0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9900: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9910: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9920: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9930: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9940: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9950: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9960: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9970: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9980: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9990: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
99a0: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
99b0: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
99c0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
99d0: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
99e0: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
99f0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9a00: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9a10: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9a20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9a30: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9a40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9a50: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9a60: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9a70: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9a80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a90: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9aa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9ab0: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9ac0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9ad0: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9ae0: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9af0: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9b00: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9b10: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9b20: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9b30: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9b40: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9b50: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9b60: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9b70: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9b80: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9b90: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9ba0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9bb0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9bc0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9bd0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9be0: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9bf0: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9c00: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9c10: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9c20: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9c30: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9c40: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9c50: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9c60: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9c70: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9c80: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9c90: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9ca0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9cb0: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9cc0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9cd0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9ce0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9cf0: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9d00: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9d10: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9d20: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9d30: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9d40: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9d50: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9d60: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9d70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9d80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9d90: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9da0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9db0: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9dc0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9dd0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9de0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9df0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9e00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e10: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9e20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9e30: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9e40: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9e50: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9e60: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9e70: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9e80: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9e90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9ea0: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9eb0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9ec0: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9ed0: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9ee0: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9ef0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9f00: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9f10: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9f20: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9f30: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9f40: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9f50: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9f60: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9f70: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9f80: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9f90: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9fa0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9fb0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9fc0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9fd0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fe0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9ff0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
a000: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a010: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
a020: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a030: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
a040: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
a050: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
a060: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
a070: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
a080: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
a090: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
a0a0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a0b0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
a0c0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
a0d0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
a0e0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
a0f0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
a100: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
a110: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
a120: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
a130: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
a140: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
a150: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
a160: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
a170: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
a180: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
a190: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
a1a0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
a1b0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
a1c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a1d0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
a1e0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
a1f0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
a200: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
a210: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
a220: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
a230: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
a240: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
a250: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
a260: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
a270: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a280: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
a290: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a2a0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
a2b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
a2c0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
a2d0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
a2e0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
a2f0: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
a300: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
a310: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
a320: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
a330: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
a340: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
a350: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
a360: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
a370: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
a380: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
a390: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
a3a0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
a3b0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
a3c0: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
a3d0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a3e0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a3f0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a400: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a410: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a440: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a450: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a460: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a470: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a480: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a490: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a4a0: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a4b0: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a4c0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a4d0: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a4e0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a4f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a500: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a510: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a520: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a530: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a540: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a550: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a560: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a570: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a580: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a590: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a5a0: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a5b0: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a5c0: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a5d0: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a5e0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a5f0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a600: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a610: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a620: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a630: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a640: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a650: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a660: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a670: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a680: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a690: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a6a0: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a6b0: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a6c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a6d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a6e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a6f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a700: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a710: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a720: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a730: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a740: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a750: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a760: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a770: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a780: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a790: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a7a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a7b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a7c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a7d0: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a7e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a800: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a810: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a820: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a830: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a840: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a850: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a860: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a870: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a880: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a890: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a8a0: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a8b0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a8c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a8d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a8e0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a8f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a900: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a910: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a920: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a930: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a940: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a950: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a960: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a970: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a980: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a990: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a9a0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a9b0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a9c0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a9d0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a9e0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a9f0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
aa00: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
aa10: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
aa20: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
aa30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
aa40: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aa50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aa60: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
aa70: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
aa80: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
aa90: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
aaa0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
aab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
aac0: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
aad0: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
aae0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
aaf0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
ab00: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
ab10: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
ab20: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
ab30: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
ab40: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
ab50: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
ab60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab70: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
ab80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ab90: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
aba0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
abb0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
abc0: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
abd0: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
abe0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
abf0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
ac00: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
ac10: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
ac20: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
ac30: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ac40: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ac50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ac60: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
ac70: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
ac80: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
ac90: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
aca0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
acb0: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
acc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
acd0: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
ace0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
acf0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
ad00: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
ad10: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
ad20: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
ad30: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
ad40: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
ad50: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
ad60: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
ad70: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
ad80: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
ad90: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
ada0: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
adb0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
adc0: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
add0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
ade0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
adf0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
ae00: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
ae10: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
ae20: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
ae30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ae40: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
ae50: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ae60: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
ae70: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
ae80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
ae90: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
aea0: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
aeb0: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
aec0: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
aed0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
aee0: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
aef0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af00: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
af10: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
af20: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
af30: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
af40: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
af50: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
af60: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
af70: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
af80: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
af90: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
afa0: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
afb0: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
afc0: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
afd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
afe0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aff0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
b000: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
b010: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
b020: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
b030: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
b040: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
b050: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
b060: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b070: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
b080: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
b090: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
b0a0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
b0b0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
b0c0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
b0d0: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
b0e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b0f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
b100: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
b110: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
b120: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
b130: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
b140: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
b150: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
b160: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
b170: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
b180: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
b190: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
b1a0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
b1b0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
b1c0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
b1d0: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
b1e0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
b1f0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b200: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
b210: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
b220: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
b230: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
b240: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
b250: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
b260: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b270: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
b280: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
b290: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
b2a0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
b2b0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
b2c0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
b2d0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
b2e0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
b2f0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
b300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b310: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b320: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b330: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
b340: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
b350: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
b360: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
b370: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b380: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b390: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b3a0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
b3b0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
b3c0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
b3d0: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b3e0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b3f0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b400: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b410: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b420: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b430: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b440: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b450: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b460: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b470: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b480: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b490: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b4a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b4b0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b4c0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b4d0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b4e0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b4f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b500: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b510: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b520: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b530: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b540: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b550: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b560: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b570: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b580: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b590: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5a0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b5b0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b5c0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b5d0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b5e0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b5f0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b600: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b610: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b620: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b630: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b640: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b650: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b660: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b670: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b680: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b690: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b6a0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b6b0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b6c0: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b6d0: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b6e0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b6f0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b700: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b710: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b720: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b730: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b740: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b750: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b760: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b770: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b780: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b790: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b7a0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b7b0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b7c0: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b7d0: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b7e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b7f0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b800: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b810: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b820: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b830: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b840: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b850: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b860: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b870: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b880: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b890: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b8a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b8b0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b8c0: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b8d0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b8e0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b8f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b900: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b910: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b920: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b930: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b940: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b950: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b960: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b970: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b980: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b990: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b9a0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b9b0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b9c0: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b9d0: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b9e0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b9f0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ba00: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ba10: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
ba20: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
ba30: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
ba40: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
ba50: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
ba60: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
ba70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ba80: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
ba90: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
baa0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
bab0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
bac0: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
bad0: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
bb00: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bb10: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
bb20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bb30: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
bb40: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
bb50: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
bb60: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
bb70: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
bb80: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
bb90: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bba0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bbb0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
bbc0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
bbd0: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
bbe0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
bbf0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
bc00: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
bc10: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
bc20: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
bc30: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
bc40: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
bc50: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
bc60: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
bc70: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
bc80: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
bc90: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
bca0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
bcb0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
bcc0: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
bcd0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
bce0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
bcf0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
bd00: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
bd10: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
bd20: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
bd30: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
bd40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bd50: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
bd60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bd70: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
bd80: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
bd90: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
bda0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
bdb0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
bdc0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
bdd0: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
bde0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
bdf0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be00: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
be10: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
be20: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
be30: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
be40: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
be50: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
be60: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
be70: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
be80: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
be90: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bea0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
beb0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bec0: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
bed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bee0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bef0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf00: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf10: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bf20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bf30: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bf40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bf50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bf60: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bf70: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
bf80: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
bf90: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
bfa0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
bfb0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
bfc0: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
bfd0: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
bfe0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bff0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
c000: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
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 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c030: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c040: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c050: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
c060: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
c070: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
c080: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
c090: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c0a0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
c0b0: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
c0c0: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
c0d0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c0e0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c0f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c100: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c110: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
c120: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
c130: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
c140: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c150: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c160: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c170: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c180: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
c190: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
c1a0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
c1b0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
c1c0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
c1d0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
c1e0: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
c1f0: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
c200: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
c210: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
c220: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
c230: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
c240: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
c250: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
c260: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
c270: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
c280: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c290: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c2a0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c2b0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c2c0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c2d0: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
c2e0: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
c2f0: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
c300: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
c310: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
c320: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
c330: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
c340: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
c350: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
c360: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
c370: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
c380: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
c390: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
c3a0: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
c3b0: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
c3c0: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
c3d0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c3e0: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c3f0: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c400: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c410: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c420: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c430: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c440: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c450: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c460: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c470: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c480: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c490: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c4a0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c4b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c4c0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c4d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c4e0: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c4f0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c500: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c510: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c520: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c530: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c540: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c550: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c560: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c570: 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  pcode.  .**.** <
c580: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c590: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c5a0: 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65  RITE]].** If the
c5b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c5c0: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c5d0: 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e  E] opcode return
c5e0: 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65  s SQLITE_OK, the
c5f0: 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65  n.** the file de
c600: 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63  scriptor is plac
c610: 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69  ed in "batch wri
c620: 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a  te mode", which.
c630: 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62  ** means all sub
c640: 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70  sequent write op
c650: 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  erations will be
c660: 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f   deferred and do
c670: 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79  ne.** atomically
c680: 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51   at the next [SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c6a0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  T_ATOMIC_WRITE].
c6b0: 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61    Systems.** tha
c6c0: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  t do not support
c6d0: 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72   batch atomic wr
c6e0: 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e  ites will return
c6f0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c700: 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20  ..** ^Following 
c710: 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c  a successful SQL
c720: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64  ATOMIC_WRITE and
c740: 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65   prior to.** the
c750: 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45   closing [SQLITE
c760: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c770: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a  OMIC_WRITE] or.*
c780: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c790: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c7a0: 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77  WRITE], SQLite w
c7b0: 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56  ill make.** no V
c7c0: 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  FS interface cal
c7d0: 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ls on the same [
c7e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69  sqlite3_file] fi
c7f0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a  le descriptor.**
c800: 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c   except for call
c810: 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20  s to the xWrite 
c820: 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78  method and the x
c830: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
c840: 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49  od.** with [SQLI
c850: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c860: 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  NT]..**.** <li>[
c870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c880: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c890: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c8a0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c8b0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c8c0: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
c8d0: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
c8e0: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
c8f0: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
c900: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
c910: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c920: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c930: 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  to be performed 
c940: 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54  atomically..** T
c950: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c960: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
c970: 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK] if and only
c980: 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77   if the writes w
c990: 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f  ere.** all perfo
c9a0: 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  rmed successfull
c9b0: 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20  y and have been 
c9c0: 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72  committed to per
c9d0: 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e  sistent storage.
c9e0: 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
c9f0: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
ca00: 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  t it is successf
ca10: 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f  ul, this file co
ca20: 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74  ntrol takes.** t
ca30: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
ca40: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
ca50: 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68  write mode so th
ca60: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
ca70: 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  t.** write opera
ca80: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
ca90: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
caa0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cab0: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cac0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cad0: 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20  RITE without.** 
cae0: 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
caf0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49  ul call to [SQLI
cb00: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cb10: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a  TOMIC_WRITE]..**
cb20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cb30: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cb40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cb50: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cb60: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cb70: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
cb80: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
cb90: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
cba0: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
cbb0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
cbc0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cbe0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
cbf0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  be rolled back..
cc00: 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f  ** ^This file co
cc10: 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20  ntrol takes the 
cc20: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
cc30: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
cc40: 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68  te mode.** so th
cc50: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
cc60: 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t write operatio
cc70: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
cc80: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
cc90: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cca0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
ccb0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ccc0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
ccd0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cce0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
ccf0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd00: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cd10: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cd20: 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f  FCNTL_LOCK_TIMEO
cd30: 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  UT]].** The [SQL
cd40: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
cd50: 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63  IMEOUT] opcode c
cd60: 61 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74  auses attempts t
cd70: 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69  o obtain.** a fi
cd80: 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68  le lock using th
cd90: 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c  e xLock or xShmL
cda0: 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ock methods of t
cdb0: 68 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a  he VFS to wait.*
cdc0: 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69  * for up to M mi
cdd0: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
cde0: 65 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65  e failing, where
cdf0: 20 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65   M is the single
ce00: 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e   .** unsigned in
ce10: 74 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e  teger parameter.
ce20: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
ce30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ce40: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
ce50: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
ce60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce70: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ce80: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
ce90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cea0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
ceb0: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
cec0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
ced0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
cee0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
cef0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
cf00: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
cf10: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
cf30: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
cf40: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
cf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
cf60: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
cf70: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
cf80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
cf90: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
cfa0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
cfb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
cfc0: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
cfd0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
cfe0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
cff0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
d000: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
d010: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
d020: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
d030: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d040: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
d050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
d060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d070: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
d080: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
d090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d0a0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
d0b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
d0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d0d0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
d0e0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
d0f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d100: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
d110: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
d120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d130: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
d140: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
d150: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d160: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
d170: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
d180: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d190: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
d1a0: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
d1b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d1c0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
d1d0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
d1e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
d1f0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
d200: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
d210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d220: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
d230: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
d240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
d250: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
d260: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
d270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
d280: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
d290: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
d2a0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
d2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d2c0: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
d2d0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
d2e0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
d2f0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
d300: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
d310: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
d320: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d330: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
d340: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
d350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d360: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
d370: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
d380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d390: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
d3a0: 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23  C_WRITE     31.#
d3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d3c0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
d3d0: 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64  C_WRITE    32.#d
d3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d3f0: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
d400: 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65  IC_WRITE  33.#de
d410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d420: 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20  L_LOCK_TIMEOUT  
d430: 20 20 20 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20           34../* 
d440: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
d450: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d460: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
d470: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
d480: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
d490: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
d4a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
d4b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
d4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
d4d0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
d4e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
d4f0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
d500: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d510: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
d520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
d530: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
d540: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
d550: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
d560: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
d570: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
d580: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
d590: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
d5a0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
d5b0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
d5c0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
d5d0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
d5e0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
d5f0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
d600: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
d610: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
d620: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d630: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
d640: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
d650: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d660: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
d670: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
d680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
d690: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
d6a0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
d6b0: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
d6c0: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
d6d0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
d6e0: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
d6f0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d700: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
d710: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
d720: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
d730: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
d740: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
d750: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
d760: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
d770: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
d780: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
d790: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
d7a0: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
d7b0: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
d7c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d7d0: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
d7e0: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
d7f0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
d800: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
d810: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
d820: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
d830: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d840: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
d850: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
d860: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
d870: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
d880: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
d890: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
d8a0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
d8b0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
d8c0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
d8d0: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
d8e0: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
d8f0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
d900: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
d910: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
d920: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
d930: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
d940: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
d950: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
d960: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
d970: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
d980: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
d990: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
d9a0: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
d9b0: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
d9c0: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
d9d0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
d9e0: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
d9f0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
da00: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
da10: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
da20: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
da30: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
da40: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
da50: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
da60: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
da70: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
da80: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
da90: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
daa0: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
dab0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
dac0: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
dad0: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
dae0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
daf0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
db00: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
db10: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
db20: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
db30: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
db40: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
db50: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
db60: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
db70: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
db80: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
db90: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
dba0: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
dbb0: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
dbc0: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
dbd0: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
dbe0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
dbf0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
dc00: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
dc10: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
dc20: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
dc30: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
dc40: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
dc50: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
dc60: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
dc70: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
dc80: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
dc90: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
dca0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
dcb0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
dcc0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
dcd0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
dce0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
dcf0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
dd00: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
dd10: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
dd20: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
dd30: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
dd40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
dd50: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
dd60: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
dd70: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
dd80: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
dd90: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
dda0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
ddb0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
ddc0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
ddd0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
dde0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
ddf0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
de00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
de10: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
de20: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
de30: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
de40: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
de50: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
de60: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
de70: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
de80: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
de90: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
dea0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
deb0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
dec0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
ded0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
dee0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
def0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
df00: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
df10: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
df20: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
df30: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
df40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
df50: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
df60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
df70: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
df80: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
df90: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
dfa0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
dfb0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
dfc0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
dfd0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
dfe0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
dff0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e000: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e010: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e020: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e030: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e040: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e050: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e060: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e070: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e080: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e090: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e0a0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e0b0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e0c0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e0d0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e0e0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e0f0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e100: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e110: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e120: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e130: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e140: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
e150: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
e160: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
e170: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
e180: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
e190: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
e1a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
e1b0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
e1c0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
e1d0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
e1e0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
e1f0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
e200: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
e210: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
e220: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e230: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
e240: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
e250: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
e260: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
e270: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
e280: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
e290: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
e2a0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
e2b0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
e2c0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
e2d0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
e2e0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
e2f0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
e300: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e310: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
e320: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
e330: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
e340: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
e350: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
e360: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
e370: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
e380: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
e390: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e3a0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
e3b0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
e3c0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
e3d0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
e3e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
e3f0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
e400: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e410: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
e420: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
e430: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
e440: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
e450: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
e460: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e470: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
e480: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
e490: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
e4a0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
e4b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e4c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e4d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e4e0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
e4f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
e500: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
e510: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e520: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e530: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
e540: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e550: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
e560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e570: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
e580: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e590: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
e5a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e5b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
e5c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
e5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
e5e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
e5f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e600: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
e610: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e620: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
e630: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
e640: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
e650: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
e660: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
e670: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
e680: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
e690: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
e6a0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
e6b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e6c0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
e6d0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
e6e0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
e6f0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
e700: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
e710: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
e720: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
e730: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
e740: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
e750: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
e760: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
e770: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
e780: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
e790: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
e7a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e7b0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
e7c0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
e7d0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
e7e0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
e7f0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
e800: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
e810: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
e820: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
e830: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
e840: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
e850: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
e860: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e870: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e880: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
e890: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e8a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e8b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e8c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
e8d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e8e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
e8f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e900: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e910: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
e920: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e930: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
e940: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
e950: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e960: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e970: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
e980: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
e990: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
e9a0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
e9b0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
e9c0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
e9d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
e9e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e9f0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
ea00: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
ea10: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
ea20: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ea30: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
ea40: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
ea50: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
ea60: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
ea70: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
ea80: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
ea90: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
eaa0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
eab0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
eac0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
ead0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
eae0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
eaf0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
eb00: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
eb10: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
eb20: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
eb30: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
eb40: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
eb50: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
eb60: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
eb70: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
eb80: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
eb90: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
eba0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
ebb0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
ebc0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
ebd0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
ebe0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
ebf0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
ec00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
ec10: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
ec20: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
ec30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
ec40: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
ec50: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
ec60: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
ec70: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
ec80: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
ec90: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
eca0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
ecb0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
ecc0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
ecd0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
ece0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
ecf0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
ed00: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ed10: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
ed20: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
ed30: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
ed40: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
ed50: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
ed60: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
ed70: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
ed80: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
ed90: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
eda0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
edb0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
edc0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
edd0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
ede0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
edf0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
ee00: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
ee10: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
ee20: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ee30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
ee40: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
ee50: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
ee60: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
ee70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ee80: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
ee90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
eea0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
eeb0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
eec0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
eed0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
eee0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
eef0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
ef00: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
ef10: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
ef20: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
ef30: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
ef40: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
ef50: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
ef60: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
ef70: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
ef80: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
ef90: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
efa0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
efb0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
efc0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
efd0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
efe0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
eff0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
f000: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
f010: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f020: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
f030: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
f040: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
f050: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
f060: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
f070: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
f080: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
f090: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
f0a0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
f0b0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
f0c0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
f0d0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
f0e0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
f0f0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
f100: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
f110: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
f120: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
f130: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
f140: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
f150: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
f160: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
f170: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
f180: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
f190: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
f1a0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
f1b0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
f1c0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
f1d0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
f1e0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
f1f0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
f200: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
f210: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
f220: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
f230: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
f240: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
f250: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
f260: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
f270: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
f280: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
f290: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
f2a0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
f2b0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
f2c0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
f2d0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
f2e0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
f2f0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
f300: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
f310: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
f320: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
f330: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
f340: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f350: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
f360: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
f370: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
f380: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
f390: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
f3a0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
f3b0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
f3c0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
f3d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f3e0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
f3f0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f400: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
f410: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
f420: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
f430: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
f440: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
f450: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
f460: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
f470: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f480: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
f490: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
f4a0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
f4b0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
f4c0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
f4d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
f4e0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
f4f0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
f500: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
f510: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
f520: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
f530: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
f540: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
f550: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
f560: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
f570: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
f580: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
f590: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
f5a0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
f5b0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
f5c0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
f5d0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
f5e0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
f5f0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
f600: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
f610: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
f620: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
f630: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
f640: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
f650: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
f660: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
f670: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
f680: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
f690: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
f6a0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
f6b0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
f6c0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
f6d0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
f6e0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
f6f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
f700: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
f710: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
f720: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
f730: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
f740: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
f750: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
f760: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
f770: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
f780: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
f790: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
f7a0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
f7b0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
f7c0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
f7d0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
f7e0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
f7f0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
f800: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
f810: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f820: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
f830: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
f840: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f850: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
f860: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
f870: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
f880: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f890: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
f8a0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
f8b0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
f8c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
f8d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
f8e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
f8f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
f900: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
f910: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
f920: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
f930: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
f940: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
f950: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
f960: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
f970: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f980: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
f990: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
f9a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
f9b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f9c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
f9d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
f9e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
f9f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
fa00: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
fa10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
fa20: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
fa30: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
fa40: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
fa50: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
fa60: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
fa70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fa80: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fa90: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
faa0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
fab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fad0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
fae0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
faf0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
fb00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fb10: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
fb20: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
fb30: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
fb40: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
fb50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fb60: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
fb70: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
fb80: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
fb90: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
fba0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
fbb0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
fbc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
fbd0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
fbe0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
fbf0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
fc00: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
fc10: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
fc20: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
fc30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fc40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
fc50: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
fc60: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
fc70: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
fc80: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
fc90: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
fca0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
fcb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
fcc0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
fcd0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
fce0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
fcf0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
fd00: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
fd10: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
fd20: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
fd30: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
fd40: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
fd50: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
fd60: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
fd70: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
fd80: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
fd90: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
fda0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
fdb0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
fdc0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
fdd0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
fde0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
fdf0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fe00: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
fe10: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
fe20: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
fe30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
fe40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fe50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fe60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
fe70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fe80: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
fe90: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
fea0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
feb0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fec0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fed0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
fee0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
fef0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ff00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ff10: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ff20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ff30: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
ff40: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
ff50: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ff60: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
ff70: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
ff80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
ff90: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
ffa0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
ffb0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
ffc0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
ffd0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
ffe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fff0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
10000 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
10010 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
10020 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
10030 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
10040 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10050 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10060 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10070 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10080 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10090 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
100a0 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
100b0 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
100c0 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
100d0 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
100e0 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
100f0 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
10100 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
10110 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
10120 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
10130 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10140 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10150 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10160 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10170 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10180 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10190 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
101a0 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
101b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
101c0 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
101d0 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
101e0 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
101f0 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10200 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10210 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10220 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10230 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10240 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10250 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10260 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
10270 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10280 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10290 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
102a0 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
102b0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
102c0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
102d0 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
102e0 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
102f0 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
10300 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10310 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
10320 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
10330 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
10340 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
10350 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
10360 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
10370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10380 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
10390 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
103a0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
103b0 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
103c0 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
103d0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
103e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
103f0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10400 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10410 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10420 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10430 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10440 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10450 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10460 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10470 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10480 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10490 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
104a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
104b0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
104c0 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
104d0 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
104e0 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
104f0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10500 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10510 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10520 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10530 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10540 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10550 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10560 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10570 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10580 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10590 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
105a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
105b0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
105c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
105d0 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
105e0 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
105f0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10600 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10610 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10620 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10630 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10640 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10650 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10660 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10670 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10680 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10690 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
106a0 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
106b0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
106c0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
106d0 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
106e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
106f0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10700 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10710 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10720 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10730 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10740 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
10750 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10760 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
10770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10780 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
10790 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
107a0 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
107b0 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
107c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
107d0 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
107e0 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
107f0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
10800 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
10810 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
10820 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
10830 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
10840 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
10850 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
10860 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
10870 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
10880 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
10890 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
108a0 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
108b0 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
108c0 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
108d0 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
108e0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
108f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10900 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10910 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
10920 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
10930 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
10940 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
10950 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
10960 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
10970 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
10980 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
10990 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
109a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
109b0 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
109c0 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
109d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
109e0 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
109f0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
10a00 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
10a10 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
10a20 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
10a30 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
10a40 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
10a50 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
10a60 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
10a70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
10a80 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
10a90 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
10aa0 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
10ab0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
10ac0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
10ae0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
10af0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
10b00 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
10b10 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10b20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10b30 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
10b40 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
10b50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10b60 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
10b70 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10b80 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
10b90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
10ba0 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
10bb0 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
10bc0 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
10bd0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10be0 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
10bf0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10c00 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
10c10 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
10c20 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
10c30 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
10c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
10c50 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
10c60 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10c70 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
10c80 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
10c90 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10ca0 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
10cb0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
10cc0 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
10cd0 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
10ce0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
10cf0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10d00 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
10d10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10d20 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
10d30 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
10d40 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
10d50 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
10d60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
10d70 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
10d80 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
10d90 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
10da0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
10db0 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
10dc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10dd0 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
10de0 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
10df0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
10e00 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
10e10 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
10e20 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
10e30 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
10e40 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
10e50 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
10e60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
10e70 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
10e80 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10e90 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
10ea0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
10eb0 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
10ec0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10ee0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10ef0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10f10 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10f20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10f30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10f40 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10f50 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10f60 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10f70 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10f80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10f90 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10fa0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10fb0 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10fc0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10fd0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10fe0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10ff0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11000 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
11010 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
11020 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
11030 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
11040 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
11050 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11060 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11070 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11080 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11090 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
110a0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
110b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
110c0 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
110d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
110e0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
110f0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
11100 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
11110 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
11120 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
11130 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
11140 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
11150 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11160 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11170 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11180 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11190 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
111a0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
111b0 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
111c0 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
111d0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
111e0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
111f0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11210 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11220 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11230 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11240 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11250 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11260 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
11270 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11280 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11290 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
112a0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
112b0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
112c0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
112d0 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
112e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
112f0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11300 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
11310 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
11320 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
11330 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11340 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
11350 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
11360 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11370 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11380 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
11390 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
113a0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
113b0 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
113c0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
113d0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
113e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
113f0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11400 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11410 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11420 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11430 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11440 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11450 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11460 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11470 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11480 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11490 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
114a0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
114b0 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
114c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
114d0 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
114e0 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
114f0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11500 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11510 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11520 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11530 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11540 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11550 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11560 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11580 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11590 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
115a0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
115b0 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
115c0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
115d0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
115e0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
115f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11600 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11620 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11630 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11640 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11650 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11660 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11680 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11690 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
116a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
116b0 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
116c0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
116d0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
116e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
116f0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11700 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11710 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11720 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11730 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11740 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
11750 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
11760 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
11770 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
11780 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
11790 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
117a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
117b0 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
117c0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
117d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
117e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
117f0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
11800 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
11810 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
11820 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
11830 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
11840 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
11850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11860 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11870 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
11880 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
11890 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
118a0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
118b0 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
118c0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
118d0 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
118e0 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
118f0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
11900 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11910 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
11920 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
11930 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
11940 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
11950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11960 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
11970 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11980 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11990 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
119a0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
119b0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
119c0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
119d0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
119e0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
119f0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11a00 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11a10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11a20 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11a40 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11a50 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11a60 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11a70 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11a80 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
11a90 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
11aa0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
11ab0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
11ac0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
11ad0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
11ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11af0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11b00 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
11b10 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
11b20 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
11b30 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11b40 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11b50 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11b60 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11b70 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11b80 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
11b90 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
11ba0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11bb0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
11bc0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
11bd0 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
11be0 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
11bf0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
11c00 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11c10 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
11c20 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
11c30 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
11c40 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
11c50 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
11c60 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
11c70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
11c80 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
11c90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11ca0 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
11cb0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
11cc0 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
11cd0 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
11ce0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
11cf0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
11d00 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
11d10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
11d20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
11d30 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
11d40 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
11d50 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11d60 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
11d70 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
11d80 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
11d90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
11da0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
11db0 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
11dc0 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
11dd0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
11de0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
11df0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
11e00 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
11e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11e20 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
11e30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
11e40 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
11e50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11e60 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
11e70 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11e80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11e90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11ea0 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11eb0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11ec0 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11ed0 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11ee0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11ef0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11f00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
11f10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11f20 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
11f30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11f40 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
11f50 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11f60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11f70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11f80 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11f90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11fa0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11fb0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11fc0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11fd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11fe0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11ff0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
12000 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
12010 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
12020 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
12030 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
12040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12050 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12060 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12070 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12080 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12090 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
120a0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
120b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
120c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
120d0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
120e0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
120f0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
12100 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
12110 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
12120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12130 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
12140 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
12150 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12160 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12170 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12180 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12190 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
121a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
121b0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
121c0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
121d0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
121e0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
121f0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
12200 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12210 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
12220 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
12230 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
12240 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
12250 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
12260 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12270 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
12280 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
12290 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
122a0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
122b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
122c0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
122d0 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
122e0 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
122f0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12300 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12310 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12320 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12330 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
12340 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
12350 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12360 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12380 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12390 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
123a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
123b0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
123c0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
123d0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
123e0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
123f0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12400 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12410 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12420 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12430 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12440 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12450 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12460 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12470 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12480 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12490 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
124a0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
124b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
124c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
124d0 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
124e0 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
124f0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12500 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12510 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12520 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12530 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12540 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12550 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12560 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12570 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12580 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12590 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
125a0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
125b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
125c0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
125d0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
125e0 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
125f0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12600 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12610 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12620 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12630 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12640 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12650 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12660 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12670 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12680 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12690 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
126a0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
126b0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
126c0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
126d0 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
126e0 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
126f0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12700 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12710 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12720 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12730 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12740 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12750 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
12760 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
12770 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12780 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12790 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
127a0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
127b0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
127c0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
127d0 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
127e0 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
127f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12800 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12810 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
12820 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
12830 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
12840 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
12850 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
12860 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
12870 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12880 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12890 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
128a0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
128b0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
128c0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
128d0 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
128e0 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
128f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12900 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12910 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
12920 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12930 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12940 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
12950 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
12960 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
12970 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12980 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12990 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
129a0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
129b0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
129c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
129d0 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
129e0 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
129f0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12a00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12a10 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12a20 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12a30 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12a40 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12a50 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a70 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12a80 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12a90 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
12aa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12ab0 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
12ac0 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
12ad0 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
12ae0 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
12af0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
12b00 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
12b10 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
12b20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
12b30 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
12b40 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
12b50 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
12b60 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
12b70 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
12b80 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
12b90 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
12ba0 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
12bb0 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
12bc0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
12bd0 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
12be0 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
12bf0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
12c00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12c10 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
12c20 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
12c30 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
12c40 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
12c50 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
12c60 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
12c70 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
12c80 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
12c90 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
12ca0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12cb0 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
12cc0 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
12cd0 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
12ce0 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
12cf0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
12d00 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
12d10 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12d20 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
12d30 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
12d40 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12d50 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
12d60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12d70 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
12d80 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
12d90 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
12da0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
12db0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
12dc0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
12dd0 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
12de0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12df0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
12e00 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
12e10 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
12e20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
12e30 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
12e40 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
12e50 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
12e60 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
12e70 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12e80 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
12e90 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
12ea0 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
12eb0 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
12ec0 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
12ed0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12ee0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ef0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
12f00 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
12f10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12f20 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
12f30 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
12f40 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
12f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12f60 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12f70 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12f80 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12f90 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12fa0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12fb0 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12fc0 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12fd0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12fe0 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12ff0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
13000 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
13010 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
13020 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
13030 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
13040 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
13050 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
13060 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
13070 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
13080 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
13090 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
130a0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
130b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
130c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
130d0 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
130e0 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
130f0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
13100 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
13110 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
13120 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
13130 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
13140 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
13150 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
13160 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13170 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
13180 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
13190 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
131a0 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
131b0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
131c0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
131d0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
131e0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
131f0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13200 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
13210 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
13220 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13230 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13240 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13250 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13260 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13270 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
13280 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
13290 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
132a0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
132b0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
132c0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
132d0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
132e0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
132f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13300 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13310 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13320 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
13330 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13340 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
13350 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
13360 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
13370 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
13380 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
13390 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
133a0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
133b0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
133c0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
133d0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
133e0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
133f0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13400 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13410 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13420 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13430 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13440 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13450 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13460 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13470 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13480 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13490 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
134a0 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
134b0 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
134c0 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
134d0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
134e0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
134f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13500 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13510 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13520 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13530 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13540 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13550 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13560 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13570 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13580 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13590 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
135a0 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
135b0 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
135c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
135d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
135e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
135f0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13600 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13610 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13620 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13630 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13640 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13650 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13660 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13670 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13690 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
136a0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
136b0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
136c0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
136d0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
136e0 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
136f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13700 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13710 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13730 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13740 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13750 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13760 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
13770 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
13780 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
13790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
137a0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
137b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
137c0 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
137d0 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
137e0 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
137f0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
13800 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
13810 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
13820 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
13830 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
13840 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
13850 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
13860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13870 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
13880 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
13890 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
138a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
138b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
138c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
138d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
138e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
138f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13900 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
13910 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
13920 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13940 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13950 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13960 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13970 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13980 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13990 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
139a0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
139b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
139d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
139e0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
139f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13a00 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13a10 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13a20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13a30 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13a40 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
13a50 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
13a60 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
13a70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
13a80 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
13a90 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
13aa0 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
13ab0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
13ac0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
13ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13ae0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
13af0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
13b00 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
13b10 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13b20 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13b30 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13b40 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
13b50 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
13b60 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
13b70 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
13b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b90 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
13ba0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
13bb0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
13bc0 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
13bd0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
13be0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13bf0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
13c00 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
13c10 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
13c20 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
13c30 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13c40 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13c50 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13c60 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13c70 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13c80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13c90 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13ca0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13cb0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13cc0 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
13cd0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
13ce0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13d00 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13d20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13d30 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13d40 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
13d50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d60 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13d80 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13d90 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
13da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13dc0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
13dd0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13de0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
13df0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13e00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13e10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13e20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13e30 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13e40 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13e50 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13e60 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13e70 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13e80 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13e90 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
13ea0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13eb0 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
13ec0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13ed0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
13ee0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
13ef0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
13f00 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13f10 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13f20 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
13f30 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
13f40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
13f50 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13f60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13f70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13f80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f90 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13fa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13fc0 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13fd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13fe0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13ff0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14000 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
14020 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14030 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
14040 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14050 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14060 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14070 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14080 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
14090 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
140a0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
140b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
140c0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
140d0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
140e0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
140f0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
14100 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
14110 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
14120 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
14130 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
14140 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
14150 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
14160 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14170 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
14180 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14190 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
141a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
141b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
141c0 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
141d0 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
141e0 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
141f0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
14200 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14210 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
14220 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
14230 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
14240 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
14250 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
14260 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
14270 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
14280 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
14290 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
142a0 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
142b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
142c0 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
142d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
142e0 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
142f0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
14300 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
14310 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
14320 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
14330 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
14340 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
14350 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
14360 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
14370 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
14380 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
143a0 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
143b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
143c0 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
143d0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
143e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
143f0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14400 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14410 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14420 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14430 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14440 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14450 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14460 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14470 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14480 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14490 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
144a0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
144b0 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
144c0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
144d0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
144e0 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
144f0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14500 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14510 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14520 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14530 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14540 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14550 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14560 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14570 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14580 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14590 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
145a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
145b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
145c0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
145d0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
145e0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
145f0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14600 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14610 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14620 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14630 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14640 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14650 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14660 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14670 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14680 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14690 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
146a0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
146b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
146c0 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
146d0 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
146e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
146f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14700 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14710 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14720 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14730 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14740 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
14750 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14760 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
14770 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14780 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
14790 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
147a0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
147b0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
147c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
147d0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
147e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
147f0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
14800 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14810 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
14820 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14830 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
14840 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
14850 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
14860 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14870 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14890 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
148a0 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
148b0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
148c0 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
148d0 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
148e0 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
148f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
14900 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
14910 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
14920 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
14930 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
14940 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
14950 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
14960 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
14970 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
14980 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
14990 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
149a0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
149b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
149c0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
149d0 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
149e0 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
149f0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
14a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14a10 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
14a20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
14a30 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14a40 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14a50 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
14a60 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
14a70 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
14a80 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
14a90 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
14aa0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
14ab0 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
14ac0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
14ad0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
14ae0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
14af0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
14b00 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
14b10 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14b20 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
14b30 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
14b40 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
14b50 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
14b60 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
14b70 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
14b80 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
14b90 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
14ba0 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
14bb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
14bc0 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
14bd0 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
14be0 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
14bf0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
14c00 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
14c10 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
14c20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
14c30 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
14c40 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
14c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14c60 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
14c70 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
14c80 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
14c90 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
14ca0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
14cb0 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
14cc0 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
14cd0 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
14ce0 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
14cf0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
14d00 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
14d10 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14d20 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14d30 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14d40 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14d50 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
14d60 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
14d70 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
14d80 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14d90 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
14da0 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
14db0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
14dc0 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
14dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14de0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
14df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14e00 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
14e10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14e20 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
14e30 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
14e40 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
14e50 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
14e60 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
14e70 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
14e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14e90 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
14ea0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
14eb0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
14ec0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14ed0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14ee0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14ef0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14f00 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14f10 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14f20 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14f30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14f40 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14f50 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14f60 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14f70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14f80 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
14f90 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14fa0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14fb0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14fc0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14fd0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14fe0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14ff0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
15000 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
15010 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
15020 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
15030 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
15040 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
15050 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15060 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
15070 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15080 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15090 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
150a0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
150b0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
150c0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
150d0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
150e0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
150f0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
15100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15110 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
15120 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
15130 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
15140 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
15150 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15160 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
15170 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15180 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15190 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
151a0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
151b0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
151c0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
151d0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
151e0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
151f0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15200 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15210 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
15220 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
15230 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15240 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
15250 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
15260 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
15270 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15280 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15290 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
152a0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
152b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
152c0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
152d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
152e0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
152f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15300 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15310 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15320 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15330 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15340 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15350 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15360 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15370 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15380 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15390 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
153a0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
153b0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
153c0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
153d0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
153e0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
153f0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15400 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15410 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15420 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15430 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15440 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15450 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15460 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15470 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15480 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15490 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
154a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
154b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
154c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
154d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
154e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
154f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15500 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15510 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15520 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15540 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15560 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15570 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15580 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15590 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
155a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
155b0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
155c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
155d0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
155e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
155f0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15600 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15610 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15620 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15630 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15640 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15650 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15660 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15670 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15680 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15690 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
156a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
156b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
156c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
156d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
156e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
156f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15700 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15710 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15720 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15730 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15740 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
15750 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
15760 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
15770 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
15780 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
15790 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
157a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
157b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
157c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
157d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
157e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
157f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15800 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15810 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15820 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15830 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15840 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15850 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15860 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
15870 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15880 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15890 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
158a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
158b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
158c0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
158d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
158e0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
158f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15900 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
15910 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15920 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15930 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
15940 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
15950 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15960 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
15970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
15980 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15990 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
159a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
159b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
159c0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
159d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
159e0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
159f0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
15a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15a10 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
15a20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
15a30 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
15a40 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
15a50 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
15a60 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15a70 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
15a80 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
15a90 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
15aa0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
15ab0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
15ac0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
15ad0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
15ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
15af0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15b10 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
15b20 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
15b30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15b40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15b50 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
15b60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15b70 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15b80 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
15b90 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15ba0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15bb0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
15bc0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
15bd0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
15be0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
15bf0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15c00 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
15c10 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15c20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15c30 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15c40 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
15c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c60 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
15c70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15c80 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15ca0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15cb0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
15cc0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15cd0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
15ce0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15cf0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15d00 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15d10 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15d20 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15d30 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15d40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15d50 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15d60 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15d70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15d80 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15d90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
15da0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
15db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15dc0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15dd0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
15de0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15df0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15e00 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15e10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15e20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15e30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15e40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15e50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15e60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15e70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15e80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15e90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15ea0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15eb0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15ec0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15ed0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15ee0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15ef0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15f00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15f10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15f20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15f30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15f40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15f50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15f60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15f70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15f80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15f90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15fa0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15fb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15fc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15fd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15fe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15ff0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
16000 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
16010 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
16020 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
16030 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
16040 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
16050 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
16060 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
16070 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16080 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16090 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
160a0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
160b0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
160c0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
160d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
160e0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
160f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16100 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
16110 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
16120 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
16130 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
16140 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16150 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
16160 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
16170 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16180 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16190 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
161a0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
161b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
161c0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
161d0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
161e0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
161f0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16200 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16210 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16220 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
16230 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
16240 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16260 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
16270 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16280 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16290 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
162a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
162b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
162c0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
162d0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
162e0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
162f0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16300 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16310 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16320 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16330 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16340 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16350 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16360 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16370 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16390 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
163a0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
163b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
163c0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
163d0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
163e0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
163f0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16400 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16410 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16420 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16430 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16440 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16450 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16460 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16470 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16480 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16490 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
164a0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
164b0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
164c0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
164d0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
164e0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
164f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16500 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16510 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16520 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16530 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16540 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16550 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16560 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16570 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16580 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16590 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
165a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
165b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
165c0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
165d0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
165e0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
165f0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16600 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16610 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16620 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16630 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16640 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16650 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16660 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16670 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16680 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16690 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
166a0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
166b0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
166c0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
166d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
166e0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
166f0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16700 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16710 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16720 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16730 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16740 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
16750 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16760 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
16770 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
16780 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
16790 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
167a0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
167b0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
167c0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
167d0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
167e0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
167f0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
16800 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
16810 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
16820 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
16830 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
16840 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
16850 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
16860 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
16870 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
16880 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
16890 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
168a0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
168b0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
168c0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
168e0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
168f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
16900 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16910 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
16920 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16930 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
16940 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
16950 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
16960 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
16970 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
16980 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
16990 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
169a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
169b0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
169c0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
169d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
169e0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
169f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16a00 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
16a10 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
16a20 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16a30 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
16a40 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16a50 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
16a60 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
16a70 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
16a80 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
16a90 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
16aa0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
16ab0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
16ac0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
16ad0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
16ae0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
16af0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
16b00 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
16b10 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
16b20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
16b30 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
16b40 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
16b50 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
16b60 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
16b70 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
16b80 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
16b90 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
16ba0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16bb0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
16bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16bd0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
16be0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16bf0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
16c00 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
16c10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16c20 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
16c30 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
16c40 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
16c50 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
16c60 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
16c70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16c80 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
16c90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
16ca0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
16cb0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
16cc0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
16cd0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
16ce0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
16cf0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16d00 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16d10 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16d20 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16d30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16d40 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16d50 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16d60 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16d70 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16d80 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16d90 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
16da0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16db0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
16dc0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
16dd0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
16de0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16df0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16e00 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16e10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16e20 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16e30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16e40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16e50 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16e60 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16e70 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16e80 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16e90 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16ea0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16eb0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16ec0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16ed0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16ee0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16ef0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16f00 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16f10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16f20 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16f30 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16f40 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16f50 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16f60 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16f70 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16f80 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
16f90 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
16fa0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
16fb0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
16fc0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16fd0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16fe0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16ff0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
17000 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
17010 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
17020 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
17030 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
17040 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
17050 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
17060 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
17070 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17080 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17090 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
170a0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
170b0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
170c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
170d0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
170e0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
170f0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
17100 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
17110 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17120 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
17130 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17140 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17150 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
17160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17170 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17180 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17190 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
171a0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
171b0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
171c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
171d0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
171e0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
171f0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17200 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17210 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
17220 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
17230 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
17240 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
17250 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
17260 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
17270 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17290 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
172a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
172b0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
172c0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
172d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
172e0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
172f0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17300 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17310 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17320 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17330 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17340 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17350 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17360 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17370 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17380 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17390 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
173a0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
173b0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
173c0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
173d0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
173e0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
173f0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17400 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17410 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17420 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17430 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17440 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17450 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17460 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17470 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17480 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17490 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
174a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
174b0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
174c0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
174d0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
174e0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
174f0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17500 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17510 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17520 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17530 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17540 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17550 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17560 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17570 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17580 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17590 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
175a0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
175b0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
175c0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
175d0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
175e0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
175f0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17600 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17610 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17620 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17630 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17640 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17650 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17660 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17670 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17680 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17690 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
176a0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
176b0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
176c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
176d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
176e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
176f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17700 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17710 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17720 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17730 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17740 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
17750 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
17760 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
17770 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
17780 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
17790 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
177a0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
177b0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
177c0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
177d0 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
177e0 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
177f0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
17800 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
17810 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
17820 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
17830 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
17840 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
17850 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
17860 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
17870 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
17880 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
17890 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
178a0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
178b0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
178c0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
178d0 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
178e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
178f0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
17900 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
17910 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
17920 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
17930 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
17940 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
17950 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17960 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
17970 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
17980 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
17990 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  RREF_SIZE.** <dd
179a0 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
179b0 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
179c0 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73  E option accepts
179d0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
179e0 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28  ter.** of type (
179f0 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76  int) - the new v
17a00 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74  alue of the sort
17a10 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a  er-reference siz
17a20 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20  e threshold..** 
17a30 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51  Usually, when SQ
17a40 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74  Lite uses an ext
17a50 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72  ernal sort to or
17a60 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f  der records acco
17a70 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f  rding.** to an O
17a80 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
17a90 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69  all fields requi
17aa0 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  red by the calle
17ab0 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e  r are present in
17ac0 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72   the.** sorted r
17ad0 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c  ecords. However,
17ae0 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   if SQLite deter
17af0 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74  mines based on t
17b00 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
17b10 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63  .** of a table c
17b20 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76  olumn that its v
17b30 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  alues are likely
17b40 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67   to be very larg
17b50 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68  e - larger.** th
17b60 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65  an the configure
17b70 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  d sorter-referen
17b80 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
17b90 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72  d - then a refer
17ba0 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65  ence.** is store
17bb0 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64  d in each sorted
17bc0 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20   record and the 
17bd0 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20  required column 
17be0 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a  values loaded.**
17bf0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
17c00 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72  se as records ar
17c10 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f  e returned in so
17c20 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20  rted order. The 
17c30 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
17c40 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
17c50 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65   is to never use
17c60 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
17c70 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  on. Specifying a
17c80 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61   .** negative va
17c90 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
17ca0 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65  ion restores the
17cb0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
17cc0 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  ur..** This opti
17cd0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17ce0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17cf0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
17d00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
17d10 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46  NABLE_SORTER_REF
17d20 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65  ERENCES] compile
17d30 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
17d40 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17d60 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
17d70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17d80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17d90 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
17da0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17db0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17dc0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
17dd0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
17de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17df0 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
17e00 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
17e10 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17e30 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
17e40 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
17e50 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
17e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
17e80 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f       6  /* No lo
17e90 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
17ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17eb0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
17ec0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
17ed0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
17ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ef0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
17f00 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
17f10 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
17f20 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
17f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
17f40 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
17f50 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
17f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17f70 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
17f80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
17f90 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
17fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17fb0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
17fc0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
17fd0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
17fe0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
17ff0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
18000 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
18010 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
18020 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
18030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18040 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
18050 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18060 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18070 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
18080 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
180a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
180b0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
180c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
180d0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
180e0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
180f0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
18100 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18110 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
18120 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18130 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18140 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
18150 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
18160 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
18170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18180 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
18190 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
181a0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
181b0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
181c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
181d0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
181e0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
181f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18200 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
18210 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
18220 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
18230 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18240 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
18250 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
18260 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
18270 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
18280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
18290 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
182a0 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
182b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
182c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
182d0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
182e0 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
182f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18300 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
18310 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
18320 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
18330 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
18340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
18350 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
18360 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
18370 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
18380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
18390 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  L_MALLOC        
183a0 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a  27  /* boolean *
183b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
183c0 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
183d0 46 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20  F_SIZE      28  
183e0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
183f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18400 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
18410 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
18420 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
18430 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
18440 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
18450 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
18460 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
18470 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
18480 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
18490 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
184a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
184b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
184c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
184d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
184e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
184f0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
18500 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
18510 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
18520 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18530 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
18540 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
18550 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
18560 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
18570 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
18580 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18590 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
185a0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
185b0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
185c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
185d0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
185e0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
185f0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
18600 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
18610 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
18620 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
18630 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
18640 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
18650 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
18660 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
18670 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
18680 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18690 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
186a0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
186b0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
186c0 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
186d0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
186e0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
186f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
18700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18710 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
18720 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
18730 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
18740 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
18750 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
18760 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
18770 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
18780 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
18790 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
187a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
187b0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
187c0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
187d0 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
187e0 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
187f0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
18800 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
18810 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
18820 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
18830 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18840 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
18850 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
18860 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
18870 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18880 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
18890 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
188a0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
188b0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
188c0 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
188d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
188e0 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
188f0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
18900 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
18910 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
18920 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
18930 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
18940 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
18950 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
18960 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
18970 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
18980 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
18990 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
189a0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
189b0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
189c0 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
189d0 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
189e0 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
189f0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
18a00 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
18a10 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
18a20 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
18a30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18a40 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
18a50 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
18a60 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
18a70 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
18a80 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
18a90 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
18aa0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
18ab0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
18ac0 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
18ad0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
18ae0 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
18af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18b00 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
18b10 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
18b20 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
18b30 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
18b40 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
18b50 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
18b60 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
18b70 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
18b80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
18b90 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
18ba0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
18bb0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
18bc0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18bd0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18be0 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
18bf0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18c00 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18c10 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
18c20 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
18c30 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
18c40 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
18c50 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
18c60 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18c70 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
18c80 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
18c90 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
18ca0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18cb0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
18cc0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18cd0 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
18ce0 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
18cf0 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
18d00 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
18d10 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
18d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18d40 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18d50 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18d60 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18d70 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
18d80 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
18d90 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
18da0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18db0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18dc0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18de0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18df0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18e00 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18e10 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
18e20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18e30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18e40 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
18e50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18e60 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18e70 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18e80 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
18e90 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
18ea0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18eb0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18ec0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18ed0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18ee0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18ef0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18f00 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
18f10 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
18f20 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
18f30 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
18f40 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
18f50 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
18f60 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18f70 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18f80 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
18f90 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
18fa0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
18fb0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18fc0 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
18fd0 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
18fe0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
18ff0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19000 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19010 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19020 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19030 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19040 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
19050 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
19060 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
19070 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19080 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
19090 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e  3_TOKENIZER</dt>
190a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
190b0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
190c0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
190d0 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d  le the two-argum
190e0 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ent.** version o
190f0 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65  f the [fts3_toke
19100 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  nizer()] functio
19110 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20  n which is part 
19120 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d  of the.** [FTS3]
19130 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
19140 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69  h engine extensi
19150 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  on..** There sho
19160 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
19170 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19180 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19190 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
191a0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
191b0 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f  to disable fts3_
191c0 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a  tokenizer() or.*
191d0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
191e0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
191f0 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76  zer() or negativ
19200 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
19210 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
19220 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
19230 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19250 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19260 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19270 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19280 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33  ate whether fts3
19290 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69  _tokenizer is di
192a0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
192b0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
192c0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
192d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
192e0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
192f0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19300 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
19310 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19320 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19330 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19340 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19350 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
19360 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ION</dt>.** <dd>
19370 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
19380 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19390 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b  or disable the [
193a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
193b0 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74  ension()].** int
193c0 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65  erface independe
193d0 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61  ntly of the [loa
193e0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
193f0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
19400 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
19410 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
19420 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65  on()] API enable
19430 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f  s or disables bo
19440 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  th the.** C-API 
19450 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
19460 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74  tension()] and t
19470 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19480 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
19490 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  )]..** There sho
194a0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
194b0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
194c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72  .** When the fir
194d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
194e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
194f0 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68   1, then only th
19500 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e  e C-API is.** en
19510 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51  abled and the SQ
19520 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69  L function remai
19530 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66  ns disabled.  If
19540 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19550 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
19560 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
19570 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
19580 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
19590 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
195a0 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
195b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
195c0 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
195d0 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
195e0 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
195f0 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
19600 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
19610 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
19620 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19630 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19640 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19650 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19660 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19670 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
19680 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19690 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
196a0 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
196b0 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
196c0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
196d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
196e0 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
196f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19700 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
19710 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
19720 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
19730 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
19740 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19750 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
19760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19770 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19780 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
19790 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61   name of the "ma
197a0 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  in" database.** 
197b0 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f  schema.  ^The so
197c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  le argument is a
197d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
197e0 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69  nstant UTF8 stri
197f0 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  ng.** which will
19800 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20   become the new 
19810 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70  schema name in p
19820 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20  lace of "main". 
19830 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73   ^SQLite.** does
19840 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79   not make a copy
19850 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e   of the new main
19860 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72   schema name str
19870 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c  ing, so the appl
19880 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
19890 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
198a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
198b0 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46  into this DBCONF
198c0 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63  IG option is unc
198d0 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20  hanged.** until 
198e0 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61  after the databa
198f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
19900 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  oses..** </dd>.*
19910 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
19920 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
19930 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  _ON_CLOSE</dt>.*
19940 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20  * <dd> Usually, 
19950 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
19960 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63  in wal mode is c
19970 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65  losed or detache
19980 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74  d from a .** dat
19990 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51  abase handle, SQ
199a0 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74  Lite checks if t
199b0 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68  his will mean th
199c0 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77  at there are now
199d0 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69   no .** connecti
199e0 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68  ons at all to th
199f0 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73  e database. If s
19a00 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61  o, it performs a
19a10 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20   checkpoint .** 
19a20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65  operation before
19a30 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e   closing the con
19a40 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70  nection. This op
19a50 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64  tion may be used
19a60 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20   to.** override 
19a70 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20  this behaviour. 
19a80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19a90 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19aa0 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  is operation.** 
19ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20  is an integer - 
19ac0 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61  positive to disa
19ad0 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  ble checkpoints-
19ae0 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72  on-close, or zer
19af0 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  o (the.** defaul
19b00 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65  t) to enable the
19b10 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20  m, and negative 
19b20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19b30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
19b40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19b50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19b60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19b70 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68  er.** into which
19b80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19b90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19ba0 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e  hether checkpoin
19bb0 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68  ts-on-close.** h
19bc0 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65  ave been disable
19bd0 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72  d - 0 if they ar
19be0 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  e not disabled, 
19bf0 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a  1 if they are..*
19c00 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19c10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19c20 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64  G_ENABLE_QPSG</d
19c30 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  t>.** <dd>^(The 
19c40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19c50 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69  ENABLE_QPSG opti
19c60 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
19c70 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
19c80 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65  he [query planne
19c90 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72  r stability guar
19ca0 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20  antee] (QPSG).  
19cb0 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73  When the QPSG is
19cc0 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69   active,.** a si
19cd0 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73  ngle SQL query s
19ce0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c  tatement will al
19cf0 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
19d00 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61  e algorithm rega
19d10 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c  rdless.** of val
19d20 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  ues of [bound pa
19d30 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65  rameters].)^ The
19d40 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73   QPSG disables s
19d50 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  ome query optimi
19d60 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  zations.** that 
19d70 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75  look at the valu
19d80 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61  es of bound para
19d90 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61  meters, which ca
19da0 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72  n make some quer
19db0 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20  ies.** slower.  
19dc0 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73  But the QPSG has
19dd0 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f   the advantage o
19de0 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62  f more predictab
19df0 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69  le behavior.  Wi
19e00 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61  th.** the QPSG a
19e10 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69  ctive, SQLite wi
19e20 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
19e30 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61  e same query pla
19e40 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  n in the field a
19e50 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75  s.** was used du
19e60 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20  ring testing in 
19e70 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20  the lab..** The 
19e80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19e90 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
19ea0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19eb0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19ec0 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c  le .** the QPSG,
19ed0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19ee0 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67  ble QPSG, or neg
19ef0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19f00 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
19f10 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63  changed. The sec
19f20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19f30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19f40 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19f50 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19f60 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19f70 63 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65  cate whether the
19f80 20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65   QPSG is disable
19f90 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19fa0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19fb0 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  all..** </dd>.**
19fc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19fd0 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
19fe0 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EQP</dt>.** <dd>
19ff0 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
1a000 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41   output of EXPLA
1a010 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f  IN QUERY PLAN co
1a020 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20  mmands does not 
1a030 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70  .** include outp
1a040 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61  ut for any opera
1a050 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20  tions performed 
1a060 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  by trigger progr
1a070 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74  ams. This.** opt
1a080 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73  ion is used to s
1a090 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65  et or clear (the
1a0a0 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67   default) a flag
1a0b0 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68   that governs th
1a0c0 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20  is.** behavior. 
1a0d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1a0e0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1a0f0 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  is operation is 
1a100 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20  an integer -.** 
1a110 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1a120 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72  le output for tr
1a130 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20  igger programs, 
1a140 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  or zero to disab
1a150 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67  le it,.** or neg
1a160 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1a170 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1a180 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
1a190 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a1a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a1b0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1a1c0 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a  ich is written .
1a1d0 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  ** 0 or 1 to ind
1a1e0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75  icate whether ou
1a1f0 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72  tput-for-trigger
1a200 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62  s has been disab
1a210 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69  led - 0 if .** i
1a220 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65  t is not disable
1a230 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20  d, 1 if it is.  
1a240 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a250 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a260 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1a270 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  SE</dt>.** <dd> 
1a280 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44  Set the SQLITE_D
1a290 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1a2a0 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20  TABASE flag and 
1a2b0 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43  then run.** [VAC
1a2c0 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  UUM] in order to
1a2d0 20 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73   reset a databas
1a2e0 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70  e back to an emp
1a2f0 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77  ty database.** w
1a300 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e  ith no schema an
1a310 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68  d no content. Th
1a320 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63  e following proc
1a330 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66  ess works even f
1a340 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f  or.** a badly co
1a350 72 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65  rrupted database
1a360 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   file:.** <ol>.*
1a370 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1a380 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1a390 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1a3a0 45 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20  ET_DATABASE, 1, 
1a3b0 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c  0);.** <li> [sql
1a3c0 69 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22  ite3_exec](db, "
1a3d0 5b 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c  [VACUUM]", 0, 0,
1a3e0 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c   0);.** <li> sql
1a3f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64  ite3_db_config(d
1a400 62 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  b, SQLITE_DBCONF
1a410 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53  IG_RESET_DATABAS
1a420 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f  E, 0, 0);.** </o
1a430 6c 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65  l>.** Because re
1a440 73 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61  setting a databa
1a450 73 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76  se is destructiv
1a460 65 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62  e and irreversib
1a470 6c 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65  le, the.** proce
1a480 73 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20  ss requires the 
1a490 75 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63  use of this obsc
1a4a0 75 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74  ure API and mult
1a4b0 69 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65  iple steps to he
1a4c0 6c 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61  lp.** ensure tha
1a4d0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61  t it does not ha
1a4e0 70 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74  ppen by accident
1a4f0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ..** </dd>.** </
1a500 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1a510 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1a520 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20  AINDBNAME       
1a530 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e       1000 /* con
1a540 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66  st char* */.#def
1a550 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1a560 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
1a570 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
1a580 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
1a590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a5a0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a5b0 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
1a5c0 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
1a5d0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1a5e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a5f0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
1a600 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
1a610 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a620 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a630 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
1a640 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
1a650 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a660 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a670 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
1a680 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
1a690 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1a6a0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a6b0 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
1a6c0 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a  OSE      1006 /*
1a6d0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1a6e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1a6f0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
1a700 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20             1007 
1a710 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1a720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a730 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1a740 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30  QP           100
1a750 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  8 /* int int* */
1a760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a770 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1a780 41 54 41 42 41 53 45 20 20 20 20 20 20 20 20 31  ATABASE        1
1a790 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  009 /* int int* 
1a7a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a7b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20  E_DBCONFIG_MAX  
1a7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a7d0 20 31 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74   1009 /* Largest
1a7e0 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a   DBCONFIG */../*
1a7f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
1a800 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1a810 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
1a820 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
1a830 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a840 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1a850 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
1a860 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
1a870 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1a880 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
1a890 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
1a8a0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
1a8b0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
1a8c0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
1a8d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
1a8e0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
1a8f0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
1a900 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
1a910 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1a920 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
1a930 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
1a940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a950 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
1a960 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
1a970 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
1a980 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
1a990 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
1a9a0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
1a9b0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
1a9c0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
1a9d0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
1a9e0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
1a9f0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
1aa00 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
1aa10 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
1aa20 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
1aa30 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
1aa40 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
1aa50 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
1aa60 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
1aa70 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
1aa80 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
1aa90 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
1aaa0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
1aab0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
1aac0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
1aad0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
1aae0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
1aaf0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
1ab00 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
1ab10 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
1ab20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ab30 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1ab40 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
1ab50 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
1ab60 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
1ab70 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
1ab80 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
1ab90 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
1aba0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
1abb0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
1abc0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
1abd0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
1abe0 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
1abf0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1ac00 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
1ac10 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
1ac20 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1ac30 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1ac40 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
1ac50 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
1ac60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ac70 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
1ac80 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1ac90 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
1aca0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
1acb0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
1acc0 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
1acd0 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
1ace0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
1acf0 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
1ad00 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
1ad10 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1ad20 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
1ad30 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
1ad40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1ad50 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1ad60 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
1ad70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1ad80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
1ad90 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
1ada0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1adb0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
1adc0 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
1add0 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
1ade0 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
1adf0 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
1ae00 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
1ae10 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
1ae20 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ae30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
1ae40 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
1ae50 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1ae60 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
1ae70 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
1ae80 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
1ae90 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
1aea0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
1aeb0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1aec0 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
1aed0 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
1aee0 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
1aef0 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
1af00 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
1af10 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
1af20 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
1af30 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
1af40 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1af50 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1af60 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
1af70 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
1af80 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
1af90 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
1afa0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1afb0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
1afc0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
1afd0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
1afe0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1aff0 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
1b000 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1b010 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
1b020 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
1b030 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
1b040 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b050 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
1b060 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
1b070 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
1b080 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
1b090 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
1b0a0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
1b0b0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
1b0c0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
1b0d0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
1b0e0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
1b0f0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
1b100 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1b110 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b120 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
1b130 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
1b140 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
1b150 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
1b160 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
1b170 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
1b180 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
1b190 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
1b1a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1b1b0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1b1c0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
1b1d0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
1b1e0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
1b1f0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
1b200 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
1b210 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
1b220 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
1b230 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
1b240 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
1b250 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
1b260 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
1b270 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
1b280 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
1b290 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
1b2a0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
1b2b0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
1b2c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1b2d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
1b2e0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
1b2f0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1b300 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
1b310 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
1b320 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
1b330 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
1b340 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
1b350 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
1b360 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1b370 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
1b380 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1b390 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
1b3a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b3b0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1b3c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1b3d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1b3e0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1b3f0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1b400 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1b410 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1b420 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1b430 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1b440 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1b450 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1b460 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1b470 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1b480 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1b490 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1b4a0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1b4b0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1b4c0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1b4d0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1b4e0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1b4f0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1b500 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1b510 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
1b520 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1b530 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b540 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1b550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b560 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1b570 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1b580 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b590 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1b5a0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1b5b0 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1b5c0 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1b5d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1b5e0 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1b5f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1b600 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1b610 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b620 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1b630 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1b640 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1b650 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
1b660 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1b670 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1b680 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
1b690 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
1b6a0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1b6b0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1b6c0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1b6d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b6e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1b6f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1b700 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1b710 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1b720 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1b730 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b740 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1b750 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b760 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1b770 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1b780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1b790 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1b7a0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1b7b0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1b7c0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1b7d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1b7e0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1b7f0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1b800 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1b810 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1b820 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1b830 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1b840 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1b850 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1b860 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1b870 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1b880 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1b890 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1b8a0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1b8b0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1b8c0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1b8d0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1b8e0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1b8f0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1b900 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1b910 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1b920 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1b930 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1b940 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1b950 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1b960 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1b970 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1b980 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b990 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1b9a0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1b9b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1b9c0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1b9d0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1b9e0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1b9f0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1ba00 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1ba10 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1ba20 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1ba30 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1ba40 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1ba50 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1ba60 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1ba70 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1ba80 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1ba90 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1baa0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1bab0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1bac0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1bad0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1bae0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1baf0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1bb00 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1bb10 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1bb20 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1bb30 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1bb40 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1bb50 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1bb60 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1bb70 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1bb80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1bb90 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1bba0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1bbb0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1bbc0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1bbd0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1bbe0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1bbf0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1bc00 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1bc10 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1bc20 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1bc30 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1bc40 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1bc50 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1bc60 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1bc70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1bc80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1bc90 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1bca0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1bcb0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1bcc0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1bcd0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1bce0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1bcf0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1bd00 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1bd10 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1bd20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1bd30 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1bd40 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1bd50 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1bd60 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1bd70 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1bd80 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1bd90 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1bda0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1bdb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1bdc0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1bdd0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1bde0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1bdf0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1be00 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1be10 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1be20 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1be30 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1be40 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1be50 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1be60 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1be70 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1be80 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1be90 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1bea0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1beb0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1bec0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1bed0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1bee0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1bef0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1bf00 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1bf10 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1bf20 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1bf30 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1bf40 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1bf50 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1bf60 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1bf70 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1bf80 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1bf90 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1bfa0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1bfb0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1bfc0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1bfd0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1bfe0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1bff0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1c000 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1c010 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1c020 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1c030 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1c040 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1c050 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1c060 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1c070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1c080 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1c090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c0a0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1c0b0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1c0c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c0d0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1c0e0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c0f0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1c100 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1c110 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1c120 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1c130 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1c140 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1c150 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1c160 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1c170 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c180 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1c190 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1c1a0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1c1b0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1c1c0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1c1d0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1c1e0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1c1f0 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1c200 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1c210 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1c220 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c230 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1c240 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1c250 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1c260 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1c270 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1c280 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1c290 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1c2a0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1c2b0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1c2c0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1c2d0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1c2e0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1c2f0 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1c300 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1c310 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1c320 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1c330 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1c340 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1c350 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1c360 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1c370 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1c380 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1c390 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1c3a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1c3b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1c3c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1c3d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1c3e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1c3f0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1c400 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1c410 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1c420 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1c430 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1c440 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1c450 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1c460 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1c470 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1c480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1c490 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1c4a0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1c4b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c4c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c4d0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1c4e0 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1c4f0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1c500 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1c510 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1c520 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1c530 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1c540 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1c550 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1c560 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1c570 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1c580 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1c590 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1c5a0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1c5b0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1c5c0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1c5d0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1c5e0 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1c5f0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1c600 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1c610 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1c620 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1c630 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1c640 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1c650 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1c660 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1c670 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1c680 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1c690 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1c6a0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1c6b0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1c6c0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1c6d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c6e0 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1c6f0 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1c700 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1c710 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1c720 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1c730 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1c740 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1c750 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1c760 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1c770 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1c780 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1c790 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1c7a0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1c7b0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1c7c0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1c7d0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1c7e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c7f0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1c800 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1c810 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1c820 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1c830 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1c840 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1c850 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1c860 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1c870 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1c880 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1c890 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1c8a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1c8b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c8c0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1c8d0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1c8e0 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1c8f0 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1c900 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1c910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c920 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1c930 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1c940 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c950 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c960 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1c970 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1c980 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1c990 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1c9a0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1c9b0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1c9c0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1c9d0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1c9e0 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1c9f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ca00 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1ca10 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1ca20 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1ca30 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1ca40 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1ca50 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1ca60 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1ca70 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1ca80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ca90 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1caa0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1cab0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1cac0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1cad0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1cae0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1caf0 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1cb00 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1cb10 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1cb20 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1cb30 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1cb40 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1cb50 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f  call returns..*/
1cb60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
1cb70 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1cb80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cb90 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1cba0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1cbb0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1cbc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1cbd0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1cbe0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1cbf0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1cc00 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1cc10 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1cc20 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1cc30 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1cc40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1cc50 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1cc60 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1cc70 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1cc80 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1cc90 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1cca0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1ccb0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1ccc0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1ccd0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1cce0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1ccf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1cd00 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1cd10 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1cd20 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1cd30 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1cd40 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1cd50 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1cd60 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1cd70 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1cd80 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1cd90 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1cda0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1cdb0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1cdc0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1cdd0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1cde0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1cdf0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1ce00 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1ce10 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1ce20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1ce30 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1ce40 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1ce50 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1ce60 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1ce70 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1ce80 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1ce90 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1cea0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1ceb0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1cec0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1ced0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1cee0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1cef0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1cf00 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1cf10 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1cf20 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1cf30 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1cf40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1cf50 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1cf60 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1cf70 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1cf80 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1cf90 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1cfa0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1cfb0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1cfc0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1cfd0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1cfe0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1cff0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1d000 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1d010 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1d020 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1d030 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1d040 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1d050 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1d060 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1d070 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1d080 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1d090 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1d0a0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1d0b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1d0c0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1d0d0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1d0e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1d0f0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1d100 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1d110 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1d120 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1d130 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1d140 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1d150 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1d160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1d170 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1d180 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1d190 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1d1a0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1d1b0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1d1c0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
1d1d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1d1e0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1d1f0 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
1d200 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1d210 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1d220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d230 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1d240 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1d250 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1d260 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1d270 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1d280 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1d290 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1d2a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1d2b0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1d2c0 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1d2d0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1d2e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d2f0 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1d300 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1d310 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1d320 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1d330 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1d340 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1d350 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1d360 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1d370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1d380 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1d390 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1d3a0 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1d3b0 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1d3c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d3d0 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1d3e0 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1d3f0 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1d400 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1d410 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1d420 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1d430 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1d440 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1d450 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1d460 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1d470 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1d480 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1d490 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1d4a0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1d4b0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1d4c0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1d4d0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1d4e0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1d4f0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1d500 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1d510 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1d520 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1d530 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1d540 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1d550 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1d560 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1d570 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1d580 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1d590 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1d5a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1d5b0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1d5c0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1d5d0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1d5e0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1d5f0 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1d600 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1d610 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1d620 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1d630 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d640 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1d650 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1d660 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1d670 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1d680 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1d690 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1d6a0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1d6b0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1d6c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d6d0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1d6e0 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1d6f0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1d700 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1d710 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1d720 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1d730 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1d740 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1d750 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1d760 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1d770 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1d780 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1d790 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1d7a0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1d7b0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1d7c0 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1d7d0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1d7e0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1d7f0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1d800 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1d810 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1d820 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d830 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1d840 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1d850 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1d860 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1d870 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1d880 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1d890 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1d8a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1d8b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1d8c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1d8d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1d8e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1d8f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1d900 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1d910 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1d920 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1d930 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1d940 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1d950 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1d960 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1d970 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1d980 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1d990 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1d9a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1d9b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1d9c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1d9d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1d9e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1d9f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1da00 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1da10 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1da20 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1da30 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1da40 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1da50 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1da60 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1da70 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1da80 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1da90 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1daa0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1dab0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1dac0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1dad0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1dae0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1daf0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1db00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1db10 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1db20 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1db30 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1db40 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1db50 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1db60 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1db70 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1db80 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1db90 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1dba0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1dbb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1dbc0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1dbd0 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1dbe0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1dbf0 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1dc00 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1dc10 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1dc20 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1dc30 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1dc40 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1dc50 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1dc60 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1dc70 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1dc80 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1dc90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dca0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1dcb0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1dcc0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1dcd0 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1dce0 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1dcf0 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1dd00 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1dd10 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1dd20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1dd30 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1dd40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1dd50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1dd60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1dd70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dd80 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1dd90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1dda0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ddb0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1ddc0 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1ddd0 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1dde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ddf0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1de00 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1de10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1de20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1de30 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1de40 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1de50 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1de60 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1de70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1de80 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1de90 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1dea0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1deb0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1dec0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1ded0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1dee0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1def0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1df00 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1df10 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1df20 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1df30 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1df40 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1df50 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1df60 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1df70 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1df80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1df90 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1dfa0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1dfb0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1dfc0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1dfd0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1dfe0 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1dff0 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1e000 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1e010 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1e020 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1e030 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1e040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e050 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1e060 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1e070 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1e080 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1e090 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1e0a0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1e0b0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1e0c0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1e0d0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1e0e0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1e0f0 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1e100 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1e110 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1e120 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1e130 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1e140 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1e150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1e160 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1e170 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1e180 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1e190 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1e1a0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1e1b0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1e1c0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1e1d0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1e1e0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1e1f0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1e200 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1e210 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1e220 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1e230 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1e240 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1e250 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1e260 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1e270 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1e280 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1e290 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1e2a0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1e2b0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1e2c0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1e2d0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1e2e0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1e2f0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1e300 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1e310 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1e320 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1e330 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1e340 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1e350 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1e360 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1e370 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1e380 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1e390 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1e3a0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1e3b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1e3c0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1e3d0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1e3e0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1e3f0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1e400 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1e410 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1e420 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1e430 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1e440 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1e450 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1e460 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1e470 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1e480 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1e490 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1e4a0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1e4b0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1e4c0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1e4d0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1e4e0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1e4f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1e500 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1e510 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1e520 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1e530 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1e540 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1e550 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1e560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1e570 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1e580 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1e590 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1e5a0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1e5b0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1e5c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1e5d0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1e5e0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1e5f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e600 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1e610 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1e620 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1e630 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1e640 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1e650 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1e660 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1e670 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1e680 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1e690 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1e6a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e6b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e6c0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1e6d0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1e6e0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1e6f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1e700 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1e710 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1e720 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1e730 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1e740 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1e750 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e760 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1e770 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1e780 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1e790 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1e7a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1e7b0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1e7c0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1e7d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1e7e0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1e7f0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1e800 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1e810 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1e820 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1e830 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e840 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1e850 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1e860 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1e870 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1e880 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1e890 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1e8a0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1e8b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e8c0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1e8d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e8e0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1e8f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e900 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1e910 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1e920 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1e930 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1e940 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e950 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1e960 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e970 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1e980 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e990 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1e9a0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1e9b0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1e9c0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1e9d0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1e9e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e9f0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1ea00 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1ea10 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1ea20 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1ea30 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1ea40 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1ea50 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1ea60 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1ea70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1ea80 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1ea90 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1eaa0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1eab0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1eac0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ead0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1eae0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1eaf0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1eb00 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1eb10 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1eb20 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1eb30 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1eb40 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1eb50 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1eb60 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1eb70 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1eb80 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1eb90 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1eba0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1ebb0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1ebc0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1ebd0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ebe0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1ebf0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1ec00 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1ec10 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1ec20 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ec30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1ec40 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1ec50 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1ec60 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1ec70 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1ec80 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1ec90 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1eca0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1ecb0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1ecc0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1ecd0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1ece0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1ecf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ed00 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1ed10 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1ed20 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1ed30 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1ed40 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ed50 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ed60 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ed70 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ed80 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ed90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1eda0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1edb0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1edc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1edd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ede0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1edf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ee00 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1ee10 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1ee20 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ee30 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1ee40 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1ee50 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1ee60 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1ee70 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1ee80 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1ee90 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1eea0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1eeb0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1eec0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1eed0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1eee0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1eef0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1ef00 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1ef10 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1ef20 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1ef30 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1ef40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ef50 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ef60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ef70 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ef80 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1ef90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1efa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1efb0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1efc0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1efd0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1efe0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1eff0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1f000 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1f010 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1f020 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1f030 6d 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  mon formatting o
1f040 70 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74  ptions from.** t
1f050 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
1f060 61 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a  ary printf() .**
1f070 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1f080 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1f090 72 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d  rd formats ([%q]
1f0a0 2c 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e  , [%Q], [%w], an
1f0b0 64 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20  d [%z])..** See 
1f0c0 74 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  the [built-in pr
1f0d0 69 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74  intf()] document
1f0e0 61 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c  ation for detail
1f0f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1f100 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1f110 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1f120 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1f130 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1f140 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1f150 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1f160 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f170 36 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  64()]..** The st
1f180 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1f190 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1f1a0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1f1b0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1f1c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1f1d0 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1f1e0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1f1f0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1f200 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
1f210 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1f220 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1f230 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1f240 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1f250 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1f260 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1f270 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1f280 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1f290 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1f2a0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1f2b0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1f2c0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1f2d0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1f2e0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1f2f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f300 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1f310 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1f320 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1f330 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f340 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1f350 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1f360 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1f370 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1f380 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1f390 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1f3a0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1f3b0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1f3c0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1f3d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1f3e0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1f3f0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1f400 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1f410 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f420 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1f430 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1f440 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1f450 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1f460 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1f470 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1f480 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1f490 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1f4a0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1f4b0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1f4c0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1f4d0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1f4e0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1f4f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f500 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f510 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1f520 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1f530 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1f540 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1f550 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1f560 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1f570 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1f580 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1f590 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1f5a0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1f5b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1f5c0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1f5d0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1f5e0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1f5f0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1f600 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1f610 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1f620 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1f630 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1f640 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1f650 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1f660 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1f670 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1f680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1f690 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1f6a0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1f6b0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1f6c0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1f6d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62  ** See also:  [b
1f6e0 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1f6f0 5d 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c  ], [printf() SQL
1f700 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68   function].*/.ch
1f710 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1f720 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1f730 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1f740 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1f750 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1f760 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1f770 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1f780 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f790 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1f7a0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1f7b0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f7c0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f7d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f7e0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1f7f0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1f800 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1f810 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1f820 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1f830 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1f840 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1f850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1f860 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1f870 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1f880 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1f890 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1f8a0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1f8b0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1f8c0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1f8d0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1f8e0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1f8f0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1f900 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1f910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1f930 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1f940 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1f950 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1f960 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1f970 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1f980 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1f990 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1f9a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1f9b0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1f9c0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1f9d0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1f9e0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1f9f0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1fa00 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1fa10 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fa20 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1fa30 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1fa40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1fa50 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1fa60 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1fa70 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1fa80 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1fa90 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1faa0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fab0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1fac0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1fad0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1fae0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1faf0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1fb00 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1fb10 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1fb20 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1fb30 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1fb40 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1fb50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1fb60 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1fb70 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1fb80 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1fb90 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1fba0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1fbb0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1fbc0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1fbd0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1fbe0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1fbf0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1fc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1fc10 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1fc20 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1fc30 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1fc40 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1fc50 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1fc60 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1fc70 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1fc80 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1fc90 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1fca0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1fcb0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1fcc0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fcd0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1fce0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1fcf0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1fd00 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1fd10 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1fd20 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1fd30 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1fd40 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1fd50 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1fd60 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1fd70 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1fd80 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1fd90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1fda0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fdb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fdc0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1fdd0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1fde0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1fdf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1fe00 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1fe10 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1fe20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1fe30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fe40 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1fe50 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1fe60 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1fe70 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1fe80 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1fe90 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1fea0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1feb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1fec0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1fed0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1fee0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1fef0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ff00 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ff10 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ff20 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ff30 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ff40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ff50 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ff60 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ff70 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ff80 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1ff90 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1ffa0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1ffb0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1ffc0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1ffd0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1ffe0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1fff0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
20000 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
20010 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
20020 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
20030 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
20040 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
20050 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
20060 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20070 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
20080 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
20090 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
200a0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
200b0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
200c0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
200d0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
200e0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
200f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
20100 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
20110 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
20120 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
20130 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
20140 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
20150 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
20160 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
20170 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
20180 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
20190 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
201a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
201b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
201c0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
201d0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
201e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
201f0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20200 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
20210 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
20220 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
20230 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
20240 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
20250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20260 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
20270 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20280 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
20290 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
202a0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
202b0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
202c0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
202d0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
202e0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
202f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
20300 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
20310 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
20320 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
20330 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
20340 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
20350 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
20360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
20370 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
20380 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
20390 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
203a0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
203b0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
203c0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
203d0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
203e0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
203f0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
20400 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
20410 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
20420 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20430 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
20440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
20450 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20460 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
20470 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
20480 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
20490 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
204a0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
204b0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
204c0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
204d0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
204e0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
204f0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
20500 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
20510 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
20520 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
20530 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
20540 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
20550 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
20560 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
20570 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
20580 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
20590 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
205a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
205b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
205c0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
205d0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
205e0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
205f0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
20600 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
20610 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
20620 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
20630 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
20640 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
20650 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
20660 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
20670 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
20680 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
20690 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
206a0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
206b0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
206c0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
206d0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
206e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
206f0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
20700 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
20710 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
20720 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
20730 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
20740 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
20750 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
20760 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
20770 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
20780 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
20790 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
207a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
207b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
207c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
207d0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
207e0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
207f0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
20800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20810 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
20820 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
20830 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
20840 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
20850 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
20860 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
20870 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20880 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
20890 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
208a0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
208b0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
208c0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
208d0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
208e0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
208f0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
20900 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
20910 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
20920 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20930 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20940 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
20950 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
20960 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
20970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
20980 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
20990 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
209a0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
209b0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
209c0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
209d0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
209e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
209f0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
20a00 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
20a10 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
20a20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20a30 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
20a40 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
20a50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
20a60 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
20a70 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
20a80 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
20a90 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
20aa0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20ab0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
20ac0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
20ad0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
20ae0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
20af0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
20b00 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
20b10 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
20b20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
20b30 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20b40 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20b50 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
20b60 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
20b70 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
20b80 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
20b90 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
20ba0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
20bb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20bc0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
20bd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
20be0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
20bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20c00 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
20c10 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
20c20 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
20c30 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
20c40 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
20c50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20c60 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
20c70 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20c80 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
20c90 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
20ca0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
20cb0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
20cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
20cd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
20ce0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
20cf0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
20d00 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
20d10 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
20d20 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
20d30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20d40 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
20d50 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
20d60 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
20d70 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
20d80 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
20d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
20da0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
20db0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
20dc0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
20dd0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20de0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
20df0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
20e00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
20e10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
20e20 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
20e30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
20e40 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
20e50 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
20e60 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
20e70 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20e80 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
20e90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
20ea0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
20eb0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
20ec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
20ed0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
20ee0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
20ef0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
20f00 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
20f10 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
20f20 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
20f30 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
20f40 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
20f50 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
20f60 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
20f70 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
20f80 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
20f90 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
20fa0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
20fb0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
20fc0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
20fd0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
20fe0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
20ff0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
21000 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
21010 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
21020 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
21030 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
21040 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
21050 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
21060 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
21070 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
21080 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
21090 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
210a0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
210b0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
210c0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
210d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
210e0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
210f0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
21100 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
21110 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
21120 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
21130 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
21140 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
21150 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
21160 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
21170 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
21180 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
21190 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
211a0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
211b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
211c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
211d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
211e0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
211f0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
21200 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
21210 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
21220 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
21230 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
21240 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
21250 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
21260 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
21270 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
21280 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
21290 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
212a0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
212b0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
212c0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
212d0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
212e0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
212f0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
21300 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
21310 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
21320 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21330 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  k}.**.** ^This r
21340 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
21350 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
21360 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
21370 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
21380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21390 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
213a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
213b0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
213c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
213d0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
213e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
213f0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
21400 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
21410 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
21420 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
21430 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21440 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
21450 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
21460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
21470 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
21480 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
21490 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
214a0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20  epare16_v3()].  
214b0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
214c0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
214d0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
214e0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
214f0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
21500 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
21510 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
21520 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21530 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21540 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
21550 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
21560 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
21570 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21580 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
21590 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
215a0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
215b0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
215c0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
215d0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
215e0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
215f0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
21600 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
21610 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
21620 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
21630 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
21640 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
21650 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
21660 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
21670 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
21680 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21690 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
216a0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
216b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
216c0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
216d0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
216e0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
216f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21700 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21710 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
21720 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
21730 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21740 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21750 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
21760 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
21770 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21780 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
21790 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
217a0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
217b0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
217c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
217d0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
217e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
217f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21800 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21810 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
21820 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21830 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21840 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21850 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
21860 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
21870 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
21880 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
21890 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
218a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
218b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
218c0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
218d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
218e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
218f0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
21900 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21910 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
21920 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21930 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
21940 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
21950 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
21960 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
21970 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
21980 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
21990 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
219a0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
219b0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
219c0 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c  k are either NUL
219d0 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65  L pointers or ze
219e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
219f0 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f  rings.** that co
21a00 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
21a10 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
21a20 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
21a30 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41  authorized..** A
21a40 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
21a50 20 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61   always be prepa
21a60 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72  red to encounter
21a70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21a80 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  in any.** of the
21a90 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74   third through t
21aa0 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
21ab0 65 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f  ers of the autho
21ac0 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63  rization callbac
21ad0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  k..**.** ^If the
21ae0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
21af0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
21b00 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21b10 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21b20 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21b30 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
21b40 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
21b50 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
21b60 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
21b70 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
21b80 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
21b90 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
21ba0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
21bb0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
21bc0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
21bd0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
21be0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
21bf0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
21c00 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
21c10 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
21c20 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
21c30 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
21c40 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
21c50 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20  * ^When a table 
21c60 69 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  is referenced by
21c70 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20   a [SELECT] but 
21c80 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  no column values
21c90 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65   are.** extracte
21ca0 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c  d from that tabl
21cb0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69  e (for example i
21cc0 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a  n a query like.*
21cd0 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28  * "SELECT count(
21ce0 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68  *) FROM tab") th
21cf0 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52  en the [SQLITE_R
21d00 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20  EAD] authorizer 
21d10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69  callback.** is i
21d20 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
21d30 74 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20  that table with 
21d40 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68  a column name th
21d50 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  at is an empty s
21d60 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
21d70 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21d80 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
21d90 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21da0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
21db0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21dc0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
21dd0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
21de0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
21df0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
21e00 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
21e10 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
21e20 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
21e30 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
21e40 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
21e50 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
21e60 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21e70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
21e80 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
21e90 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
21ea0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
21eb0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21ec0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
21ed0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
21ee0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
21ef0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
21f00 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
21f10 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
21f20 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
21f30 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
21f40 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
21f50 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
21f60 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
21f70 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
21f80 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
21f90 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
21fa0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
21fb0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
21fc0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
21fd0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
21fe0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
21ff0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
22000 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
22010 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
22020 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
22030 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
22040 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
22050 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
22060 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
22070 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
22080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
22090 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
220a0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
220b0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
220c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
220d0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
220e0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
220f0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
22100 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
22110 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
22120 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
22130 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
22140 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
22150 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
22160 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
22170 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
22180 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
22190 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
221a0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
221b0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
221c0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
221d0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
221e0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
221f0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
22200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22210 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
22220 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
22230 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22240 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
22250 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
22260 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
22270 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22280 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
22290 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
222a0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
222b0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
222c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
222d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
222e0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
222f0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
22300 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
22310 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22320 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
22330 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
22340 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
22350 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
22360 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22370 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
22380 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
22390 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
223a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
223b0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
223c0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
223d0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
223e0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
223f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22400 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
22410 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
22420 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
22430 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
22440 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
22450 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22460 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
22470 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
22480 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
22490 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
224a0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
224b0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
224c0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
224d0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
224e0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
224f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
22500 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
22510 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22520 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
22530 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
22540 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22550 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
22560 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
22570 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
22580 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
22590 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
225a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
225b0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
225c0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
225d0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
225e0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
225f0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
22600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22610 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
22620 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
22630 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
22640 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
22650 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22660 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
22670 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
22680 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
22690 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
226a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
226b0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
226c0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
226d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
226e0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
226f0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
22700 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22710 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
22720 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
22730 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
22740 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
22750 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
22760 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
22770 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
22780 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
22790 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
227a0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
227b0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
227c0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
227d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
227e0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
227f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
22800 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22810 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22820 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
22830 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
22840 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
22850 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
22860 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
22870 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
22880 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
22890 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
228a0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
228b0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
228c0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
228d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
228e0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
228f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
22900 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
22910 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
22920 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
22930 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
22940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
22950 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
22960 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
22970 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22980 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
22990 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
229a0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
229b0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
229c0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
229d0 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
229e0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
229f0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
22a00 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
22a10 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
22a20 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
22a30 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
22a40 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
22a50 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
22a60 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
22a70 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
22a80 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
22a90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22aa0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
22ab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
22ac0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
22ad0 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
22ae0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
22af0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
22b00 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
22b10 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
22b20 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
22b30 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
22b40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22b50 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
22b60 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
22b70 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
22b80 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
22b90 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
22ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22bb0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
22bc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
22bd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22be0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
22bf0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
22c00 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
22c10 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
22c20 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
22c30 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
22c40 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
22c50 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
22c60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22c70 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
22c80 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
22c90 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
22ca0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
22cb0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
22cc0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
22cd0 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
22ce0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
22cf0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
22d00 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
22d10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d30 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
22d40 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
22d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22d60 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
22d70 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
22d80 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22d90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22da0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22db0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
22dc0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
22dd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22de0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22e00 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
22e10 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
22e20 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22e30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22e50 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
22e60 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
22e70 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22e80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22ea0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
22eb0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
22ec0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22ed0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22ef0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
22f00 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
22f10 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22f20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22f40 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
22f50 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
22f60 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22f70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22f90 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
22fa0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
22fb0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22fc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22fd0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
22fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22ff0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
23000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23020 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
23030 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
23040 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
23050 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
23060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23070 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
23080 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
23090 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
230a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
230b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
230c0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
230d0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
230e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
230f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23110 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
23120 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
23130 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23160 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
23170 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
23180 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
23190 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
231a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
231b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
231c0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
231d0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
231e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
231f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23200 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
23210 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
23220 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23230 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23250 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
23260 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
23270 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
23280 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
232a0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
232b0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
232c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
232d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
232e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
232f0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
23300 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
23310 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
23320 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
23330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
23340 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
23350 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
23360 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
23370 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
23380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
23390 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
233a0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
233b0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
233c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
233d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
233e0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
233f0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
23400 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
23410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23420 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
23430 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
23440 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
23450 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
23460 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
23470 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
23480 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23490 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
234a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
234b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
234c0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
234d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
234e0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
234f0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
23500 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23510 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
23520 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
23530 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
23540 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
23550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23560 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
23570 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
23580 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
23590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
235a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
235b0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
235c0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
235d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
235e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
235f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23600 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
23610 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
23620 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23630 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
23640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23650 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
23660 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
23670 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23680 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
23690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
236a0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
236b0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
236c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
236d0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
236e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
236f0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
23700 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
23710 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
23720 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
23730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23740 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
23750 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
23760 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
23770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23780 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
23790 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
237a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
237b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
237c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
237d0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
237e0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
237f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23800 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
23810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70  routines are dep
23820 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65  recated. Use the
23830 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23840 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  v2()] interface.
23850 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ** instead of th
23860 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72  e routines descr
23870 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ibed here..**.**
23880 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23890 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
238a0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
238b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
238c0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
238d0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
238e0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
238f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
23900 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23910 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23920 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
23930 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
23940 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
23950 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
23960 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
23970 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
23980 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
23990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
239a0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
239b0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
239c0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
239d0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
239e0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
239f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
23a00 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
23a10 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
23a20 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
23a30 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
23a40 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
23a50 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
23a60 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
23a70 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
23a80 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
23a90 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
23aa0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
23ab0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
23ac0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
23ad0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
23ae0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
23af0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
23b00 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
23b10 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
23b20 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
23b30 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
23b40 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
23b50 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
23b60 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
23b70 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
23b80 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
23b90 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
23ba0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
23bb0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
23bc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
23bd0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
23be0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
23bf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
23c00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23c10 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
23c20 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
23c30 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
23c40 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
23c50 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
23c60 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
23c70 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
23c80 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
23c90 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
23ca0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
23cb0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
23cc0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
23cd0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
23ce0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
23cf0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
23d00 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
23d10 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
23d20 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
23d30 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
23d40 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
23d50 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
23d60 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
23d70 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
23d80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
23d90 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
23da0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
23db0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
23dc0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
23dd0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
23de0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
23df0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23e00 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
23e10 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
23e20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
23e30 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
23e40 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
23e50 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
23e60 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
23e70 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23e80 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
23e90 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
23ea0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
23eb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
23ec0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
23ed0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
23ee0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
23ef0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
23f00 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
23f10 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
23f20 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
23f30 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
23f40 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
23f50 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
23f60 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
23f70 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
23f80 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
23f90 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a  The M argument.*
23fa0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
23fb0 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d  ace_v2(D,M,X,P)]
23fc0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
23fd0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
23fe0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
23ff0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
24000 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
24010 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
24020 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
24030 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
24040 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
24050 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
24060 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
24070 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
24080 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24090 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
240a0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
240b0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
240c0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
240d0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
240e0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
240f0 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
24100 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
24110 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
24120 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
24130 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
24140 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
24150 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
24160 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
24170 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
24180 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24190 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
241a0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
241b0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
241c0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
241d0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
241e0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
241f0 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
24200 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24210 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
24220 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24230 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
24240 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
24250 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
24260 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
24270 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
24280 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
24290 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
242a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
242b0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
242c0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
242d0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
242e0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
242f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24300 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
24310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24320 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
24330 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
24340 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
24350 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
24360 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
24370 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
24380 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
24390 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
243a0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
243b0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
243c0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
243d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
243e0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
243f0 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
24400 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
24410 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
24420 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
24430 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
24440 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
24450 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
24460 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
24470 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
24480 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
24490 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
244a0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
244b0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
244c0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
244d0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
244e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
244f0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
24500 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
24510 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
24520 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
24530 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
24540 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
24550 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
24560 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
24570 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
24580 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
24590 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
245a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
245b0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
245c0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
245d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
245e0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
245f0 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
24600 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
24610 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
24620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24630 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
24640 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
24650 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
24660 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
24670 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
24680 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
24690 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
246a0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
246b0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
246c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
246d0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
246e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
246f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
24700 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
24710 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
24720 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
24730 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
24740 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24750 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
24760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24770 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
24780 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
24790 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
247a0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
247b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
247c0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
247d0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
247e0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
247f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24800 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
24810 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
24820 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
24830 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24840 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
24850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24860 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
24870 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
24880 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
24890 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
248a0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
248b0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
248c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
248d0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
248e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
248f0 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
24900 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
24910 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
24920 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
24930 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
24940 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
24950 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
24960 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24970 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
24980 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
24990 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
249a0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
249b0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
249c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
249d0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
249e0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
249f0 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
24a00 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
24a10 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
24a20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
24a30 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
24a40 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
24a50 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
24a60 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
24a70 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
24a80 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
24a90 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
24aa0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
24ab0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
24ac0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
24ad0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
24ae0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
24af0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24b00 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
24b10 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
24b20 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
24b30 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
24b40 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
24b50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
24b60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24b70 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
24b80 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
24b90 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
24ba0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
24bb0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
24bc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
24bd0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
24be0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
24bf0 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
24c00 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
24c10 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
24c20 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
24c30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
24c40 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
24c50 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
24c60 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
24c70 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
24c80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24c90 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
24ca0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
24cb0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
24cc0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
24cd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
24ce0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
24cf0 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
24d00 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
24d10 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
24d20 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
24d30 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
24d40 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
24d50 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
24d60 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
24d70 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
24d80 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
24d90 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
24da0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
24db0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
24dc0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
24dd0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
24de0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
24df0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
24e00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24e10 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
24e20 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
24e30 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
24e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
24e50 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
24e60 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
24e70 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
24e80 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
24e90 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
24ea0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
24eb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24ec0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
24ed0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
24ee0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
24ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24f00 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24f10 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
24f20 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
24f30 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
24f40 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
24f50 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
24f60 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
24f70 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
24f80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
24f90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
24fa0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
24fb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
24fc0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
24fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
24fe0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
24ff0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
25000 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
25010 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
25020 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
25030 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
25040 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
25050 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
25060 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
25070 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
25080 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25090 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
250a0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
250b0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
250c0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
250d0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
250e0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
250f0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
25100 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
25110 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
25120 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
25130 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
25140 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
25150 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
25160 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
25170 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
25180 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
25190 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
251a0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
251b0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
251c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
251d0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
251e0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
251f0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
25200 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
25210 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
25220 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
25230 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25240 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
25250 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
25260 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
25270 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
25280 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
25290 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
252a0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
252b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
252c0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
252d0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
252e0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
252f0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
25300 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
25310 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
25320 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
25330 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
25340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
25350 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
25360 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
25370 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
25380 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
25390 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
253a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
253b0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
253c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
253d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
253e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
253f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25400 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
25410 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
25420 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
25430 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
25440 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
25450 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
25460 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
25470 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
25480 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
25490 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
254a0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
254b0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
254c0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
254d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
254e0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
254f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
25500 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
25510 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
25520 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
25530 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
25540 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
25550 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
25560 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
25570 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
25580 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
25590 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
255a0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
255b0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
255c0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
255d0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
255e0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
255f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25600 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
25610 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
25620 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
25630 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
25640 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
25650 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
25660 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
25670 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
25680 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
25690 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
256a0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
256b0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
256c0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
256d0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
256e0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
256f0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
25700 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
25710 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
25720 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
25730 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
25740 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
25750 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
25760 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
25770 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
25780 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
25790 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
257a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
257b0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
257c0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
257d0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
257e0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
257f0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
25800 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
25810 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
25820 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
25830 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
25840 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
25850 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
25860 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
25870 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
25880 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
25890 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
258a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
258b0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
258c0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
258d0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
258e0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
258f0 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
25900 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
25910 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25920 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
25930 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
25940 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
25950 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
25960 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
25970 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
25980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25990 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
259a0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
259b0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
259c0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
259d0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
259e0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
259f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25a00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
25a10 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
25a20 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
25a30 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
25a40 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
25a50 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
25a60 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
25a70 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
25a80 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
25a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25aa0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
25ab0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
25ac0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25ad0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
25ae0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
25af0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
25b00 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
25b10 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
25b20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
25b30 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
25b40 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
25b50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
25b60 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
25b70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
25b80 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
25b90 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
25ba0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
25bb0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
25bc0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
25bd0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
25be0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
25bf0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
25c00 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
25c10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
25c20 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
25c30 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
25c40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
25c50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
25c60 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
25c70 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
25c80 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25c90 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25ca0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
25cb0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
25cc0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
25cd0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
25ce0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
25cf0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
25d00 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
25d10 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
25d20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
25d30 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
25d40 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
25d50 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25d60 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
25d70 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
25d80 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
25d90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25da0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
25db0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
25dc0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
25dd0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
25de0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
25df0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
25e00 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
25e10 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
25e20 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
25e30 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
25e40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
25e50 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
25e60 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
25e70 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
25e80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
25e90 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25ea0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
25eb0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
25ec0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
25ed0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
25ee0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
25ef0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
25f00 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
25f10 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
25f20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
25f30 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
25f40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
25f50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
25f60 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
25f70 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
25f80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25f90 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
25fa0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
25fb0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
25fc0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
25fd0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
25fe0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
25ff0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
26000 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
26010 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
26020 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
26030 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
26040 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
26050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26060 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
26070 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
26080 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
26090 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
260a0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
260b0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
260c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
260d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
260e0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
260f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
26100 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
26110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26120 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
26130 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
26140 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
26150 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
26160 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
26170 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
26180 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
26190 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
261a0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
261b0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
261c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
261d0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
261e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
261f0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
26200 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
26210 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26220 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
26230 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
26240 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
26250 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26260 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26270 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
26280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
26290 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
262a0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
262b0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
262c0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
262d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
262e0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
262f0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
26300 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
26310 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
26320 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
26330 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
26340 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
26350 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
26360 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
26370 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
26380 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
26390 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
263a0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
263b0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
263c0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
263d0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
263e0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
263f0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
26400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
26410 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
26420 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
26430 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
26440 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
26450 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
26460 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
26470 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
26480 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
26490 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
264a0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
264b0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
264c0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
264d0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
264e0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
264f0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
26500 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
26510 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
26520 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
26530 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
26540 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
26550 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
26560 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
26570 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
26580 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
26590 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
265a0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
265b0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
265c0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
265d0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
265e0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
265f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26600 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
26610 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
26620 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
26630 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
26640 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
26650 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
26660 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
26670 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
26680 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
26690 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
266a0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
266b0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
266c0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
266d0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
266e0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
266f0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
26700 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
26710 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
26720 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
26730 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67  in the third arg
26740 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
26750 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
26760 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
26770 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
26780 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
26790 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
267a0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
267b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
267c0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
267d0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
267e0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
267f0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
26800 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
26810 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
26820 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
26830 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
26840 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
26850 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
26860 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
26870 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
26880 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
26890 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
268a0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
268b0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
268c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
268d0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
268e0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
268f0 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
26900 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
26910 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
26920 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
26930 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
26940 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
26950 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
26960 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
26970 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
26980 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
26990 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
269a0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
269b0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
269c0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
269d0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
269e0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
269f0 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
26a00 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
26a10 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
26a20 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
26a30 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
26a40 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
26a50 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
26a60 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
26a70 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
26a80 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
26a90 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
26aa0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
26ab0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
26ac0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
26ad0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
26ae0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
26af0 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
26b00 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
26b10 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
26b20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
26b30 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
26b40 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
26b50 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
26b60 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
26b70 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
26b80 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
26b90 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
26ba0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
26bb0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
26bc0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
26bd0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
26be0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26bf0 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
26c00 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
26c10 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
26c20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
26c30 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
26c40 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
26c50 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
26c60 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
26c70 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
26c80 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
26c90 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
26ca0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
26cb0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
26cc0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
26cd0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
26ce0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
26cf0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
26d00 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
26d10 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
26d20 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
26d30 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
26d40 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
26d50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
26d60 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
26d70 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
26d80 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
26d90 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
26da0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
26db0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
26dc0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
26dd0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
26de0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
26df0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
26e00 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
26e10 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
26e20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
26e30 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
26e40 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
26e50 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
26e60 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
26e70 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
26e80 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
26e90 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
26ea0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
26eb0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
26ec0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
26ed0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26ee0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26ef0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
26f00 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
26f10 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
26f20 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
26f30 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
26f40 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
26f50 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
26f60 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
26f70 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
26f80 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
26f90 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
26fa0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
26fb0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
26fc0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26fd0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
26fe0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
26ff0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
27000 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
27010 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
27020 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
27030 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
27040 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
27050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27060 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
27070 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
27080 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
27090 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
270a0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
270b0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
270c0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
270d0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
270e0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
270f0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
27100 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27110 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
27120 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
27130 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
27140 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
27150 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
27160 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
27170 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
27180 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
27190 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
271a0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
271b0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
271c0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
271d0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
271e0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
271f0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
27200 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
27210 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
27220 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
27230 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
27240 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
27250 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
27260 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
27270 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
27280 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
27290 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
272a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
272b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
272c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
272d0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
272e0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
272f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
27300 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
27310 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
27320 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
27330 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
27340 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
27350 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
27360 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
27370 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
27380 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
27390 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
273a0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
273b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
273c0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
273d0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
273e0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
273f0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
27400 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
27410 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
27420 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
27430 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
27440 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
27450 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
27460 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
27470 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
27480 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
27490 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
274a0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
274b0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
274c0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
274d0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
274e0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
274f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
27500 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
27510 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
27520 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
27530 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
27540 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
27550 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
27560 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
27570 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
27580 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
27590 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
275a0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
275b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
275c0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
275d0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
275e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
275f0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
27600 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
27610 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
27620 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
27630 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
27640 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
27650 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
27660 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
27670 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
27680 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
27690 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
276a0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
276b0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
276c0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
276d0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
276e0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
276f0 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
27700 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
27710 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
27720 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
27730 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
27740 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
27750 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
27760 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
27770 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
27780 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
27790 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
277a0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
277b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
277c0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
277d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
277e0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
277f0 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
27800 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
27810 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
27820 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
27830 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
27840 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
27850 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
27860 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
27870 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
27880 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
27890 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
278a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
278b0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
278c0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
278d0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
278e0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
278f0 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
27900 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
27910 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
27920 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
27930 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
27940 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
27950 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
27960 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
27970 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
27980 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
27990 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
279a0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
279b0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
279c0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
279d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
279e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
279f0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
27a00 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
27a10 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
27a20 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
27a30 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
27a40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
27a50 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
27a60 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
27a70 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
27a80 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
27a90 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
27aa0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
27ab0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
27ac0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
27ad0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
27ae0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
27af0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
27b00 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
27b10 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
27b20 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
27b30 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
27b40 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
27b50 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
27b60 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
27b70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27b80 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
27b90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27ba0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
27bb0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
27bc0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
27bd0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27be0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27bf0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
27c00 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
27c10 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
27c20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
27c30 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
27c40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
27c50 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
27c60 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
27c70 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
27c80 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27c90 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
27ca0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
27cb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27cc0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
27cd0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
27ce0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
27cf0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
27d00 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
27d10 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
27d20 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
27d30 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
27d40 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
27d50 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
27d60 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
27d70 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
27d80 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
27d90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
27da0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
27db0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
27dc0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
27dd0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
27de0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
27df0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
27e00 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
27e10 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
27e20 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
27e30 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
27e40 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
27e50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
27e60 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
27e70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27e80 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
27e90 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
27ea0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27eb0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
27ec0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
27ed0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
27ee0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
27ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
27f00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
27f10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
27f20 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
27f30 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
27f40 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
27f50 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
27f60 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
27f70 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
27f80 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
27f90 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
27fa0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
27fb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
27fc0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
27fd0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
27fe0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
27ff0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
28000 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
28010 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
28020 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
28030 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
28040 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
28050 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
28060 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
28070 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
28080 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
28090 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
280a0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
280b0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
280c0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
280d0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
280e0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
280f0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
28100 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
28110 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
28120 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
28130 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28140 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
28150 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
28160 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
28170 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
28180 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
28190 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
281a0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
281b0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
281c0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
281d0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
281e0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
281f0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28200 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
28210 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
28220 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
28230 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28240 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
28250 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
28260 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
28270 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
28280 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
28290 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
282a0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
282b0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
282c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
282d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
282e0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
282f0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
28300 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
28310 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
28320 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
28330 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
28340 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
28350 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
28360 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
28370 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
28380 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
28390 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
283a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
283b0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
283c0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
283d0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
283e0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
283f0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
28400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
28410 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
28420 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
28430 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
28440 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
28450 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
28460 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
28470 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
28480 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
28490 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
284a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
284b0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
284c0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
284d0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
284e0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
284f0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
28500 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28510 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
28520 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
28530 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
28540 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
28550 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
28560 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28570 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28580 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
28590 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
285a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
285b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
285c0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
285d0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
285e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
285f0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
28600 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
28610 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
28620 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
28630 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
28640 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
28650 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
28660 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
28670 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28680 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28690 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
286a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
286b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
286c0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
286d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
286e0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
286f0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
28700 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
28710 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
28720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28730 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
28740 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
28750 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
28760 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
28770 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
28780 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
28790 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
287a0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
287b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
287c0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
287d0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
287e0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
287f0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
28800 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
28810 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
28820 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
28830 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
28840 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
28850 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
28860 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
28870 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
28880 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
28890 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
288a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
288b0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
288c0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
288d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
288e0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
288f0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
28900 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
28910 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
28920 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
28930 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
28940 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28950 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
28960 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
28970 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
28980 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
28990 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
289a0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
289b0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
289c0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
289d0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
289e0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
289f0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
28a00 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
28a10 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
28a20 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
28a30 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
28a40 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
28a50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
28a60 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28a70 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
28a80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
28a90 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
28aa0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
28ab0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
28ac0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
28ad0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
28ae0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
28af0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28b00 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
28b10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
28b20 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
28b30 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
28b40 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
28b50 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
28b60 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
28b70 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
28b80 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
28b90 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
28ba0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
28bb0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
28bc0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
28bd0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
28be0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
28bf0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
28c00 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
28c10 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
28c20 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
28c30 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
28c40 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
28c50 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
28c60 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
28c70 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
28c80 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
28c90 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
28ca0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
28cb0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
28cc0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
28cd0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
28ce0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
28cf0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
28d00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
28d10 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
28d20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
28d30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
28d40 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
28d50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
28d60 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
28d70 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
28d80 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
28d90 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
28da0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
28db0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
28dc0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
28dd0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
28de0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
28df0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
28e00 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
28e10 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
28e20 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
28e30 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
28e40 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28e50 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
28e60 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
28e70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
28e80 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
28e90 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
28ea0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
28eb0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
28ec0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
28ed0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
28ee0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
28ef0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
28f00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
28f10 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
28f20 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
28f30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28f40 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
28f50 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
28f60 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
28f70 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
28f80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28f90 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
28fa0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
28fb0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
28fc0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
28fd0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
28fe0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
28ff0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
29000 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
29010 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
29020 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
29030 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
29040 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
29060 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
29070 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
29080 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
29090 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
290a0 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
290b0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
290c0 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
290d0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
290e0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
290f0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
29100 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
29110 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
29120 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
29130 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29140 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
29150 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
29160 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
29170 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
29180 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
29190 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
291a0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
291b0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
291c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
291d0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
291e0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
291f0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
29200 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29210 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
29220 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29230 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
29240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29250 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
29260 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
29270 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
29280 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
29290 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
292a0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
292b0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
292c0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
292d0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
292e0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
292f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
29300 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
29310 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
29320 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29330 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
29340 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
29350 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
29360 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
29370 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
29380 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
29390 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
293a0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
293b0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
293c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
293d0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
293e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
293f0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
29400 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29410 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
29420 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
29430 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
29440 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
29450 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
29460 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
29470 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
29480 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
29490 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
294a0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
294b0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
294c0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
294d0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
294e0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
294f0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
29500 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
29510 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
29520 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
29530 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
29540 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
29550 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
29560 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
29570 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
29580 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
29590 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
295a0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
295b0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
295c0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
295d0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
295e0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
295f0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
29600 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
29610 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
29620 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
29630 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
29640 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
29650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
29660 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
29670 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
29680 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
29690 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
296a0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
296b0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
296c0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
296d0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
296e0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
296f0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
29700 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
29710 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
29720 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
29730 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
29740 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
29750 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
29760 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
29770 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
29780 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
29790 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
297a0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
297b0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
297c0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
297d0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
297e0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
297f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
29800 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
29810 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
29820 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
29830 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
29840 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29850 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
29860 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
29870 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
29880 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
29890 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
298a0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
298b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
298c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
298d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
298e0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
298f0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
29900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
29910 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
29920 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
29930 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
29940 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
29950 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
29960 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
29970 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
29980 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
29990 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
299a0 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
299b0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
299c0 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
299d0 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
299e0 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
299f0 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
29a00 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
29a10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
29a30 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
29a40 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
29a50 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29a60 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
29a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a80 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
29a90 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
29aa0 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
29ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ac0 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
29ad0 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
29ae0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
29af0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
29b00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b10 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
29b20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29b30 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
29b40 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
29b50 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
29b60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
29b70 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
29b80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
29b90 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
29ba0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29bb0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
29bc0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
29bd0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
29be0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29bf0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
29c00 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
29c10 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
29c20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
29c30 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
29c40 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
29c50 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
29c60 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
29c70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
29c80 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
29c90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
29ca0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
29cb0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
29cc0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
29cd0 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
29ce0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
29cf0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
29d00 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
29d10 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
29d20 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
29d30 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
29d40 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
29d50 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
29d60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29d70 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
29d80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29d90 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
29da0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
29db0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
29dc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
29dd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
29de0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
29df0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
29e00 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
29e10 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
29e20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
29e30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
29e40 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
29e50 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
29e60 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
29e70 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
29e80 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
29e90 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
29ea0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
29eb0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
29ec0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
29ed0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
29ee0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
29ef0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
29f00 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
29f10 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
29f20 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
29f30 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
29f40 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
29f50 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
29f60 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
29f70 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
29f80 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
29f90 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
29fa0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
29fb0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
29fc0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
29fd0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
29fe0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
29ff0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
2a000 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
2a010 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
2a020 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2a030 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
2a040 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
2a050 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
2a060 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
2a070 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
2a080 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
2a090 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
2a0a0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
2a0b0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
2a0c0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
2a0d0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
2a0e0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
2a0f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
2a100 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
2a110 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
2a120 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
2a130 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
2a140 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
2a150 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2a160 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
2a170 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
2a180 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
2a190 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
2a1a0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
2a1b0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
2a1c0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
2a1d0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
2a1e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
2a1f0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
2a200 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
2a210 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
2a220 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
2a230 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
2a240 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
2a250 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
2a260 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
2a270 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
2a280 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
2a290 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
2a2a0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
2a2b0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
2a2c0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
2a2d0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
2a2e0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
2a2f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2a300 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
2a310 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
2a320 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
2a330 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
2a340 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
2a350 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
2a360 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
2a370 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
2a380 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
2a390 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
2a3a0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
2a3b0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
2a3c0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
2a3d0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
2a3e0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
2a3f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
2a400 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
2a410 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
2a420 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
2a430 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
2a440 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
2a450 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
2a460 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2a470 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2a480 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2a490 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
2a4a0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
2a4b0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
2a4c0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
2a4d0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
2a4e0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2a4f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
2a500 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
2a510 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
2a520 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2a530 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
2a540 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
2a550 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
2a560 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
2a570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
2a580 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
2a590 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
2a5a0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
2a5b0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
2a5c0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
2a5d0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
2a5e0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
2a5f0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
2a600 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
2a610 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
2a620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a630 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
2a640 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
2a650 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a660 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
2a670 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
2a680 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
2a690 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
2a6a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a6b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2a6c0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2a6d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2a6e0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2a6f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2a700 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
2a710 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
2a720 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
2a730 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a740 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
2a750 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2a760 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
2a770 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a780 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a790 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
2a7a0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
2a7b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2a7c0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
2a7d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a7e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
2a7f0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
2a800 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
2a810 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
2a820 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a830 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a840 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2a850 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a860 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
2a870 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
2a880 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
2a890 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
2a8a0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
2a8b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a8c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2a8d0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
2a8e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a8f0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
2a900 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a910 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
2a920 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
2a930 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2a940 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a950 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
2a960 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
2a970 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2a980 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
2a990 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a9a0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
2a9b0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
2a9c0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
2a9d0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
2a9e0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
2a9f0 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
2aa00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2aa10 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
2aa20 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
2aa30 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
2aa40 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
2aa50 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
2aa60 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
2aa70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
2aa80 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
2aa90 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2aaa0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
2aab0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2aac0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
2aad0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2aae0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
2aaf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2ab00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2ab10 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
2ab20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
2ab30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2ab40 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
2ab50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2ab60 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
2ab70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ab80 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
2ab90 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
2aba0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
2abb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
2abc0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2abd0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
2abe0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2abf0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2ac00 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
2ac10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2ac20 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
2ac30 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
2ac40 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
2ac50 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
2ac60 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
2ac70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2ac80 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2ac90 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
2aca0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2acb0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
2acc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2acd0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
2ace0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
2acf0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
2ad00 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
2ad10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
2ad20 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
2ad30 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2ad40 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
2ad50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2ad60 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2ad70 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
2ad80 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
2ad90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2ada0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2adb0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
2adc0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2add0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
2ade0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2adf0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
2ae00 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
2ae10 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
2ae20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2ae30 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
2ae40 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
2ae50 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2ae60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2ae70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2ae80 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
2ae90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2aea0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2aeb0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2aec0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2aed0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
2aee0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2aef0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
2af00 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
2af10 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
2af20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2af30 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
2af40 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
2af50 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2af60 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
2af70 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
2af80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2af90 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
2afa0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
2afb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2afc0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
2afd0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
2afe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2aff0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2b000 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
2b010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b020 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2b030 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
2b040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b050 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2b060 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
2b070 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2b080 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2b090 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
2b0a0 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
2b0b0 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67  EF: Prepare Flag
2b0c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2b0d0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2b0e0 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61  arious flags tha
2b0f0 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  t can be passed 
2b100 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61  into.** "prepFla
2b110 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66  gs" parameter of
2b120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2b130 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a  epare_v3()] and.
2b140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b150 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65  are16_v3()] inte
2b160 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  rfaces..**.** Ne
2b170 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61  w flags may be a
2b180 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
2b190 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2b1a0 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  e..**.** <dl>.**
2b1b0 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52   [[SQLITE_PREPAR
2b1c0 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e  E_PERSISTENT]] ^
2b1d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50  (<dt>SQLITE_PREP
2b1e0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f  ARE_PERSISTENT</
2b1f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2b200 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2b210 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73  RSISTENT flag is
2b220 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71   a hint to the q
2b230 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20  uery planner.** 
2b240 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2b250 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2b260 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2b270 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64   a long time and
2b280 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75  .** probably reu
2b290 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29  sed many times.)
2b2a0 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20  ^ ^Without this 
2b2b0 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70  flag, [sqlite3_p
2b2c0 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20  repare_v3()].** 
2b2d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2b2e0 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73  pare16_v3()] ass
2b2f0 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65  ume that the pre
2b300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b310 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64  will .** be used
2b320 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74   just once or at
2b330 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65   most a few time
2b340 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72  s and then destr
2b350 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
2b360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b370 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f  )] relatively so
2b380 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20  on. The current 
2b390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
2b3a0 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68  cts.** on this h
2b3b0 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20  int by avoiding 
2b3c0 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b  the use of [look
2b3d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f  aside memory] so
2b3e0 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65   as not to.** de
2b3f0 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65  plete the limite
2b400 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61  d store of looka
2b410 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74  side memory. Fut
2b420 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a  ure versions of.
2b430 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63  ** SQLite may ac
2b440 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64  t on this hint d
2b450 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c  ifferently..** <
2b460 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
2b470 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b480 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20  ERSISTENT       
2b490 20 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a         0x01../*.
2b4a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2b4b0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
2b4c0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
2b4d0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
2b4e0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2b4f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b500 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2b510 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b520 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2b530 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2b540 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2b550 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2b560 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2b570 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2b580 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2b590 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65  es.  Or, in othe
2b5a0 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72  r words, these r
2b5b0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63  outines.** are c
2b5c0 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  onstructors for 
2b5d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b5e0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
2b5f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65  .**.** The prefe
2b600 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20  rred routine to 
2b610 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f  use is [sqlite3_
2b620 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20  prepare_v2()].  
2b630 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2b640 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72  prepare()] inter
2b650 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61  face is legacy a
2b660 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  nd should be avo
2b670 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  ided..** [sqlite
2b680 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2b690 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72  has an extra "pr
2b6a0 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20  epFlags" option 
2b6b0 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20  that is used.** 
2b6c0 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70  for special purp
2b6d0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  oses..**.** The 
2b6e0 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38  use of the UTF-8
2b6f0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70   interfaces is p
2b700 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c  referred, as SQL
2b710 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  ite currently.**
2b720 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e   does all parsin
2b730 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20  g using UTF-8.  
2b740 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2b750 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
2b760 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65  ed.** as a conve
2b770 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46  nience.  The UTF
2b780 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77  -16 interfaces w
2b790 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e  ork by convertin
2b7a0 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74  g the.** input t
2b7b0 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20  ext into UTF-8, 
2b7c0 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68  then invoking th
2b7d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2b7e0 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e  UTF-8 interface.
2b7f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2b800 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2b810 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2b820 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2b830 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2b840 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2b850 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b860 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2b870 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2b880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2b890 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2b8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b8b0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2b8c0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2b8d0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2b8e0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2b8f0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2b900 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2b910 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2b920 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2b930 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2b940 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71  e3_prepare(), sq
2b950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b960 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b970 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a  e3_prepare_v3().
2b980 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
2b990 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
2b9a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b9b0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2b9c0 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2b9d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b9e0 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d  16_v3() use UTF-
2b9f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2ba00 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2ba10 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2ba20 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2ba30 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2ba40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2ba50 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2ba60 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2ba70 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2ba80 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2ba90 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2baa0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2bab0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2bac0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2bad0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2bae0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2baf0 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2bb00 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2bb10 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2bb20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2bb30 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2bb40 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2bb50 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2bb60 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2bb70 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2bb80 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2bb90 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2bba0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2bbb0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2bbc0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2bbd0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2bbe0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2bbf0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2bc00 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2bc10 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2bc20 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2bc30 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2bc40 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2bc50 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2bc60 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2bc70 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2bc80 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2bc90 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2bca0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2bcb0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2bcc0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2bcd0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2bce0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2bcf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd00 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2bd10 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2bd20 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2bd30 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2bd40 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2bd50 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2bd60 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2bd70 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2bd80 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2bd90 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2bda0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2bdb0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2bdc0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2bdd0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2bde0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2bdf0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2be00 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2be10 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2be20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2be30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2be40 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2be50 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2be60 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2be70 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2be80 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2be90 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2bea0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2beb0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2bec0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2bed0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2bee0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2bef0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2bf00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2bf10 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69  epare_v2(), sqli
2bf20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2bf30 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2bf40 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2bf50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bf60 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63  16_v3() interfac
2bf70 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64  es are recommend
2bf80 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
2bf90 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20  rograms..** The 
2bfa0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2bfb0 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   (sqlite3_prepar
2bfc0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2bfd0 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20  prepare16()).** 
2bfe0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
2bff0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2c000 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
2c010 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
2c020 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
2c030 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
2c040 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
2c050 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
2c060 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
2c070 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2c080 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
2c090 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
2c0a0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2c0b0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
2c0c0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
2c0d0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
2c0e0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
2c0f0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
2c100 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
2c110 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
2c120 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2c130 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
2c140 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
2c150 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
2c160 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
2c170 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
2c180 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
2c190 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
2c1a0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2c1b0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
2c1c0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
2c1d0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
2c1e0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
2c1f0 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
2c200 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
2c210 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
2c220 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c230 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
2c240 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
2c250 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2c260 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
2c270 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
2c280 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2c290 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
2c2a0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
2c2b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
2c2c0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2c2d0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
2c2e0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
2c2f0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
2c300 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
2c310 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
2c320 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
2c330 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
2c340 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
2c350 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
2c360 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
2c370 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
2c380 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c390 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
2c3a0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
2c3b0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
2c3c0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
2c3d0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
2c3e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
2c3f0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
2c400 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
2c410 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
2c420 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
2c430 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2c440 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2c450 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
2c460 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
2c470 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
2c480 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
2c490 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
2c4a0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
2c4b0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2c4c0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
2c4d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
2c4e0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2c4f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2c500 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
2c510 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
2c520 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
2c530 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
2c540 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
2c550 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
2c560 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
2c570 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c580 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
2c590 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
2c5a0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
2c5b0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
2c5c0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
2c5d0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
2c5e0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2c5f0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
2c600 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
2c610 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2c620 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
2c630 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
2c640 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
2c650 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
2c660 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
2c670 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
2c680 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
2c690 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
2c6a0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
2c6b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
2c6c0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
2c6d0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
2c6e0 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70  ** <p>^sqlite3_p
2c6f0 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66  repare_v3() diff
2c700 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ers from sqlite3
2c710 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e  _prepare_v2() on
2c720 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20  ly in having.** 
2c730 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c  the extra prepFl
2c740 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77  ags parameter, w
2c750 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72  hich is a bit ar
2c760 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  ray consisting o
2c770 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  f zero or.** mor
2c780 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
2c790 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2c7a0 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41  ENT|SQLITE_PREPA
2c7b0 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54  RE_*] flags.  ^T
2c7c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
2c7d0 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72  epare_v2() inter
2c7e0 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74  face works exact
2c7f0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ly the same as.*
2c800 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2c810 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65  e_v3() with a ze
2c820 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ro prepFlags par
2c830 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ameter..*/.int s
2c840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2c850 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c860 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c870 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c880 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c890 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c8a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c8b0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c8c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c8d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c8e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c8f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c900 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c910 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c920 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c930 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c940 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c950 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c960 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c970 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2c980 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c990 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2c9a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c9b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c9c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c9d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c9e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c9f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2ca00 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ca10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ca20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2ca30 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2ca40 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2ca50 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2ca60 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2ca70 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ca80 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2ca90 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2caa0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2cab0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2cac0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2cad0 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71  prepare_v3(.  sq
2cae0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2caf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2cb00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2cb10 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2cb20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2cb30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2cb40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2cb50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2cb60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2cb70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2cb80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2cb90 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2cba0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2cbb0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2cbc0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2cbd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2cbe0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2cbf0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2cc00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2cc10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2cc20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2cc30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2cc40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2cc50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cc60 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2cc70 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2cc80 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2cc90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2cca0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2ccb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ccc0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2ccd0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2cce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2ccf0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2cd00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2cd10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2cd20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2cd30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2cd40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cd50 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2cd60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2cd70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2cd80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2cd90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2cda0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2cdb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2cdc0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2cdd0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2cde0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2cdf0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ce00 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2ce10 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2ce20 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ce30 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ce40 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ce50 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ce60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ce70 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ce80 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ce90 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2cea0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2ceb0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2cec0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2ced0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2cee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cef0 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v3(.  sqlite3 
2cf00 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2cf10 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2cf20 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2cf30 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2cf40 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2cf50 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2cf60 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2cf70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cf80 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2cf90 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2cfa0 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20  . */.  unsigned 
2cfb0 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f  int prepFlags, /
2cfc0 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53  * Zero or more S
2cfd0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66  QLITE_PREPARE_ f
2cfe0 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65  lags */.  sqlite
2cff0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2d000 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2d010 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2d020 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2d030 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2d040 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2d050 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2d060 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2d070 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2d080 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2d090 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2d0a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d0b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c  ^The sqlite3_sql
2d0c0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2d0d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d0e0 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  to a copy of the
2d0f0 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65   UTF-8.** SQL te
2d100 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2d110 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d120 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61  ement] P if P wa
2d130 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2d140 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d150 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2d160 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a  _prepare_v3()],.
2d170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2d180 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
2d190 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d1a0 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v3()]..** ^Th
2d1b0 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2d1c0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2d1d0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2d1e0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2d1f0 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2d200 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2d210 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2d220 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2d230 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2d240 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2d250 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2d260 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2d270 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2d280 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2d290 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2d2a0 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2d2b0 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2d2c0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2d2d0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2d2e0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2d2f0 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2d300 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2d310 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2d320 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2d330 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2d340 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2d350 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d360 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2d370 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2d380 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2d390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2d3a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2d3b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d3c0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2d3d0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2d3e0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2d3f0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2d400 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2d410 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2d420 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2d430 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2d440 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2d450 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2d460 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2d470 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2d480 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2d490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2d4a0 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2d4b0 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2d4c0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2d4d0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2d4e0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2d4f0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2d500 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2d510 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d520 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2d530 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2d540 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2d550 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2d560 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2d570 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2d580 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2d590 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2d5a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2d5b0 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2d5c0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2d5d0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d5e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d5f0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2d600 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2d610 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2d620 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2d630 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2d640 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2d650 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2d660 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2d670 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2d680 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d690 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2d6a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2d6b0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2d6c0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2d6d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d6e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2d6f0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2d700 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2d710 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2d720 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d730 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2d740 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2d750 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2d760 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d770 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2d780 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2d790 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d7a0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2d7b0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2d7c0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2d7d0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2d7e0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2d7f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2d800 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2d820 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2d830 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2d840 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2d850 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2d860 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2d870 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2d880 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2d890 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2d8a0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2d8b0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2d8c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2d8d0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2d8e0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2d8f0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2d900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d910 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2d920 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2d930 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2d940 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2d950 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2d960 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2d970 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2d980 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2d990 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2d9a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2d9b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2d9c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2d9d0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2d9e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2d9f0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2da00 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2da10 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2da20 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2da30 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2da40 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2da50 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2da60 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2da70 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2da80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2da90 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2daa0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2dab0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2dac0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2dad0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2dae0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2daf0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2db00 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2db10 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2db20 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2db30 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2db40 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2db50 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2db60 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2db70 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2db80 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2db90 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2dba0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2dbb0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2dbc0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2dbd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2dbe0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2dbf0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2dc00 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2dc10 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2dc20 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2dc30 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2dc40 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2dc50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2dc60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2dc70 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2dc80 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2dc90 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2dca0 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2dcb0 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2dcc0 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2dcd0 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2dce0 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2dcf0 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2dd00 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2dd10 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2dd20 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2dd30 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2dd40 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2dd50 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2dd60 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2dd70 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2dd80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2dd90 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2dda0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2ddb0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2ddc0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2ddd0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2dde0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ddf0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2de00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2de10 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2de20 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2de30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2de40 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2de50 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2de60 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2de70 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2de80 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2de90 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2dea0 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2deb0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2dec0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2ded0 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2dee0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2def0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2df00 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2df10 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2df20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2df30 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2df40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2df50 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2df60 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2df70 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2df80 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2df90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dfa0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2dfb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2dfc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2dfd0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2dfe0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2dff0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2e000 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2e010 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2e020 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2e030 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2e040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e050 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2e060 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2e070 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2e080 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2e090 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2e0a0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2e0b0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2e0c0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2e0d0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2e0e0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2e0f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2e100 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2e110 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2e120 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2e130 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2e140 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2e150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2e160 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2e170 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2e180 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2e190 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e1a0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2e1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2e1c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2e1d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2e1e0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2e1f0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2e200 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2e210 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2e220 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2e230 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2e240 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2e250 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2e260 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2e270 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2e280 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2e290 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2e2a0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2e2b0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2e2c0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2e2d0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2e2e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2e2f0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2e300 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2e310 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2e320 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2e330 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2e340 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e350 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2e360 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2e370 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2e380 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2e390 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e3a0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2e3b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2e3c0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2e3d0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2e3e0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2e3f0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2e400 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2e410 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e420 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2e430 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2e440 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2e450 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2e460 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2e470 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e480 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2e490 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e4a0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2e4b0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2e4c0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2e4d0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2e4e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2e4f0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2e500 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2e510 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e520 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2e530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e540 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2e550 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2e560 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e580 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2e590 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2e5a0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2e5b0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2e5c0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2e5d0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2e5e0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2e5f0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2e600 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2e610 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2e620 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2e630 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2e640 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2e650 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2e660 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2e670 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2e680 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2e690 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e6a0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e6b0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e6c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2e6d0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2e6e0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2e6f0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2e700 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2e710 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2e720 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2e730 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2e740 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2e750 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2e760 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2e770 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2e780 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e790 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2e7a0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2e7b0 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2e7c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e7d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2e7e0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2e7f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2e800 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2e810 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2e820 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2e830 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2e840 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2e860 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2e870 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2e880 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2e890 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2e8a0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2e8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e8c0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2e8d0 62 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d  be used as argum
2e8e0 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ents.** to [sqli
2e8f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2e900 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69  ()], [sqlite3_bi
2e910 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64  nd_value()], and
2e920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2e930 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68  ue_dup()]..** Th
2e940 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e950 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2e960 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2e970 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2e980 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2e990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e9a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2e9b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2e9c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73   sqlite3_value s
2e9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2e9e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2e9f0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2ea00 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2ea10 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2ea20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2ea30 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2ea40 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2ea50 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2ea60 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2ea70 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2ea80 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2ea90 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2eaa0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2eab0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2eac0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ead0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2eae0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2eaf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2eb00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2eb10 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2eb20 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2eb30 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2eb40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2eb50 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2eb60 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2eb70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2eb80 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2eb90 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2eba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2ebb0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2ebc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2ebd0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2ebe0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2ebf0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2ec00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2ec10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2ec20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2ec30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ec40 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2ec50 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2ec60 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2ec70 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2ec80 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2ec90 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2eca0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2ecb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2ecc0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2ecd0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2ece0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2ecf0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ed00 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ed10 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2ed20 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2ed30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2ed40 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2ed50 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2ed60 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2ed70 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2ed80 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2ed90 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2eda0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2edb0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2edc0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2edd0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2ede0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2edf0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2ee00 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2ee10 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2ee20 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2ee30 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2ee40 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2ee50 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2ee60 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2ee70 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2ee80 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2ee90 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2eea0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2eeb0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2eec0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2eed0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2eee0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2eef0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2ef00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2ef10 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2ef20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ef30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ef40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ef50 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2ef60 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2ef70 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ef80 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2ef90 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2efa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2efb0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2efc0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2efd0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2efe0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2eff0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2f000 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2f010 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2f020 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2f030 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2f040 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2f050 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2f060 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2f070 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2f080 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2f090 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2f0a0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2f0b0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2f0c0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2f0d0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2f0e0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2f0f0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2f100 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2f110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2f120 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2f130 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2f140 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2f150 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2f160 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2f170 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2f180 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2f190 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2f1a0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2f1b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2f1c0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2f1d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2f1e0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2f1f0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2f200 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2f210 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2f220 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2f230 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2f240 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2f250 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2f270 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f280 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2f290 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f2a0 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2f2b0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2f2c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2f2d0 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2f2e0 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2f2f0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2f300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2f310 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2f320 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2f330 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2f340 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2f350 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2f360 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f370 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2f380 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2f390 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2f3a0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2f3b0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2f3c0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2f3d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2f3e0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2f3f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2f400 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f410 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2f420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f430 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2f440 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2f450 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2f460 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2f470 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2f480 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2f490 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2f4a0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2f4b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f4c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2f4d0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2f4e0 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2f4f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2f500 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2f510 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2f520 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2f530 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2f540 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2f550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f560 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2f570 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2f580 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2f590 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2f5a0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2f5b0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2f5c0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2f5d0 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2f5e0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2f5f0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2f600 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2f610 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2f620 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2f630 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2f640 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2f650 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2f660 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2f670 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2f680 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2f690 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2f6a0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2f6b0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2f6c0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2f6d0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2f6e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f6f0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2f700 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2f710 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2f720 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2f730 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2f740 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2f750 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2f760 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2f770 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2f780 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2f790 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2f7a0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2f7b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2f7c0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2f7d0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2f7e0 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2f7f0 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2f800 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2f810 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2f820 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2f830 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2f840 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2f850 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2f860 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2f870 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2f880 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2f890 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2f8a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2f8b0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2f8c0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2f8d0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2f8e0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2f8f0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2f900 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2f910 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2f920 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2f930 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2f940 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2f950 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2f960 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2f970 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2f980 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2f990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2f9a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2f9b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2f9c0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2f9d0 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2f9e0 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2f9f0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2fa00 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2fa10 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2fa20 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2fa30 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2fa40 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2fa50 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2fa60 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2fa70 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2fa80 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2fa90 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2faa0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2fab0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2fac0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2fad0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2fae0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2faf0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2fb00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2fb10 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2fb20 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2fb30 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2fb40 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2fb50 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2fb60 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2fb70 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2fb80 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2fb90 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2fba0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2fbb0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2fbc0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2fbd0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2fbe0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2fbf0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2fc00 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2fc10 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2fc20 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2fc30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2fc40 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2fc50 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2fc60 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2fc70 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2fc80 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2fc90 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2fca0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2fcb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fcc0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c  _bind_pointer(S,
2fcd0 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65  I,P,T,D) routine
2fce0 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68   causes the I-th
2fcf0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
2fd00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fd10 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20  ment] S to have 
2fd20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20  an SQL value of 
2fd30 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73  NULL, but to als
2fd40 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  o be.** associat
2fd50 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e  ed with the poin
2fd60 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e  ter P of type T.
2fd70 20 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61    ^D is either a
2fd80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
2fd90 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2fda0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
2fdb0 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53  nction for P. ^S
2fdc0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2fdd0 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63  e the.** destruc
2fde0 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
2fdf0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
2fe00 50 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e  P when it is fin
2fe10 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50  ished using.** P
2fe20 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74  .  The T paramet
2fe30 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73  er should be a s
2fe40 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72  tatic string, pr
2fe50 65 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e  eferably a strin
2fe60 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68  g.** literal. Th
2fe70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2fe80 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65  ointer() routine
2fe90 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
2fea0 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73  ** [pointer pass
2feb0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61  ing interface] a
2fec0 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20  dded for SQLite 
2fed0 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49  3.20.0..**.** ^I
2fee0 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2fef0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ff00 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2ff10 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2ff20 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2ff30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ff40 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2ff50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ff60 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2ff70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ff80 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2ff90 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2ffa0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2ffb0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2ffc0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2ffd0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2ffe0 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2fff0 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
30000 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
30010 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
30020 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
30030 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30040 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
30050 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
30060 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
30070 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
30080 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
30090 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
300a0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
300b0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
300c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
300d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
300e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
300f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
30100 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
30110 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
30120 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
30130 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
30140 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
30150 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
30160 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
30170 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
30180 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
30190 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
301a0 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
301b0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
301c0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
301d0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
301e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
301f0 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
30200 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
30210 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
30220 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
30230 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
30240 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
30250 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
30260 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
30270 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
30280 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30290 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
302a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
302b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
302c0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
302d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
302e0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
302f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
30300 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
30310 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30320 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
30330 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30350 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
30360 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
30370 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
30380 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
30390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
303a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
303b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
303c0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
303d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
303e0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
303f0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
30400 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30410 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
30420 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
30430 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30440 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
30450 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30460 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
30470 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
30480 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30490 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
304a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
304b0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
304c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
304d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
304e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
304f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
30500 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
30510 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
30520 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
30530 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30540 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
30550 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
30560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30570 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
30580 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
30590 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
305a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
305b0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
305c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
305d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
305e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
305f0 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74  nd_pointer(sqlit
30600 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76  e3_stmt*, int, v
30610 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
30620 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  *,void(*)(void*)
30630 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30640 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
30650 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30660 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
30670 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
30680 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
30690 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
306a0 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
306b0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
306c0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
306d0 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
306e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
306f0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
30700 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
30710 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
30720 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
30730 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
30740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30750 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
30760 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
30770 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
30780 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
30790 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
307a0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
307b0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
307c0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
307d0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
307e0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
307f0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
30800 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
30810 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
30820 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
30830 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
30840 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
30850 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
30860 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
30870 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
30880 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
30890 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
308a0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
308b0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
308c0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
308d0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
308e0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
308f0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
30900 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
30910 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
30920 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30930 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30940 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30950 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30960 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
30970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30980 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
30990 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
309a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
309b0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
309c0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
309d0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
309e0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
309f0 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
30a00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30a10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
30a20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30a30 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
30a40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
30a50 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
30a60 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
30a70 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
30a80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
30a90 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
30aa0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
30ab0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
30ac0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
30ad0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
30ae0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
30af0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
30b00 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
30b10 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
30b20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
30b30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
30b40 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
30b50 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
30b60 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
30b70 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
30b80 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
30b90 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
30ba0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
30bb0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
30bc0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
30bd0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
30be0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
30bf0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
30c00 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
30c10 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
30c20 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
30c30 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
30c40 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
30c50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
30c60 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
30c70 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
30c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
30c90 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
30ca0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
30cb0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
30cc0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
30cd0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
30ce0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
30cf0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
30d00 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
30d10 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
30d20 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
30d30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30d40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30d50 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30d60 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
30d70 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
30d80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30da0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
30db0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
30dc0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
30dd0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
30de0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30df0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
30e00 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
30e10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30e20 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
30e30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
30e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30e50 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
30e60 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
30e70 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
30e80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30e90 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
30ea0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
30eb0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
30ec0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
30ed0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
30ee0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
30ef0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
30f00 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
30f10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
30f20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
30f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
30f40 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
30f50 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
30f60 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
30f70 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
30f80 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
30f90 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
30fa0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
30fb0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
30fc0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
30fd0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
30fe0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
30ff0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31000 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  e16_v2()] or.** 
31010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31020 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
31030 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31040 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
31050 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
31060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
31070 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
31080 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
31090 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
310a0 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
310b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
310c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
310d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
310e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
310f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31100 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
31110 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
31120 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
31130 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31140 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
31150 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
31160 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
31170 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31180 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
31190 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
311a0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
311b0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
311c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
311d0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
311e0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
311f0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
31200 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
31210 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
31220 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
31230 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
31240 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31250 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
31260 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
31270 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31280 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
31290 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
312a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
312b0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
312c0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
312d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
312e0 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f  nt]. ^If this ro
312f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c  utine returns 0,
31300 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
31310 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31320 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73  atement] returns
31330 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78   no data (for ex
31340 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
31350 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c  ])..** ^However,
31360 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68   just because th
31370 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31380 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
31390 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  mber does not.**
313a0 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f   mean that one o
313b0 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64  r more rows of d
313c0 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ata will be retu
313d0 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54  rned.  ^A SELECT
313e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69   statement.** wi
313f0 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61  ll always have a
31400 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65   positive sqlite
31410 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31420 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f   but depending o
31430 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63  n the.** WHERE c
31440 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31450 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20  s and the table 
31460 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68  content, it migh
31470 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73  t return no rows
31480 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31490 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
314a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
314b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
314c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
314d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
314e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
314f0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
31500 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
31510 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
31530 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31540 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
31550 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
31560 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
31570 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
31580 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31590 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
315a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
315b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
315c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
315d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
315e0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
315f0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
31600 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
31610 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31620 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
31630 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
31640 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
31650 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
31660 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
31670 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
31680 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
31690 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
316a0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
316b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
316c0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
316d0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
316e0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
316f0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
31700 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
31710 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
31720 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
31730 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
31740 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
31750 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
31760 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31770 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
31780 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
31790 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
317a0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
317b0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
317c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
317d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
317e0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
317f0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
31800 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
31810 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
31820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31830 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
31840 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
31850 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
31860 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
31870 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
31880 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
31890 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
318a0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
318b0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
318c0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
318d0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
318e0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
318f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
31900 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
31910 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
31920 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
31930 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
31940 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
31950 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
31960 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
31970 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
31980 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
31990 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
319a0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
319b0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
319c0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
319d0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
319e0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
319f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31a00 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
31a10 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
31a20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31a30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
31a40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31a50 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
31a60 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
31a70 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
31a80 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
31a90 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31aa0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31ab0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
31ac0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
31ad0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
31ae0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
31af0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
31b00 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
31b10 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
31b20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
31b30 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
31b40 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
31b50 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
31b60 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
31b70 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
31b80 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
31b90 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
31ba0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
31bb0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
31bc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
31bd0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
31be0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
31bf0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31c00 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
31c10 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
31c20 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
31c30 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
31c40 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
31c50 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
31c60 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
31c70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31c80 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
31c90 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
31ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31cb0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
31cc0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
31cd0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
31ce0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
31cf0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
31d00 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
31d10 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
31d20 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
31d30 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
31d40 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
31d50 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
31d60 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
31d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
31d80 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
31d90 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
31da0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
31db0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
31dc0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
31dd0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
31de0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
31df0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
31e00 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
31e10 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
31e20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
31e30 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
31e40 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
31e50 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
31e60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
31e70 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
31e80 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
31e90 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
31ea0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
31eb0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
31ec0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
31ed0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
31ee0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
31ef0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
31f00 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
31f10 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
31f20 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
31f30 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
31f40 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
31f50 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
31f60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31f70 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
31f80 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
31f90 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
31fa0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
31fb0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
31fc0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
31fd0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
31fe0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
31ff0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
32000 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
32010 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
32020 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
32030 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
32040 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
32050 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
32060 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
32070 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
32080 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
32090 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
320a0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
320b0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
320c0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
320d0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
320e0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
320f0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
32100 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
32110 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
32120 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
32130 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
32140 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
32150 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
32160 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
32170 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
32180 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
32190 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
321a0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
321b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
321c0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
321d0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
321e0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
321f0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
32200 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
32210 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
32220 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
32230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
32240 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
32250 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
32260 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
32270 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
32280 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
32290 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
322a0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
322b0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
322c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
322d0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
322e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
322f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32300 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32310 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32320 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32330 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
32340 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32350 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
32360 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32370 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
32380 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32390 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
323a0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
323b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
323c0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
323d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
323e0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
323f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32400 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32410 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32420 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
32430 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32450 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
32460 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
32470 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
32480 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32490 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
324a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
324b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
324c0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
324d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
324e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
324f0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
32500 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
32510 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
32520 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
32530 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
32540 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
32550 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
32560 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
32570 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
32580 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
32590 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
325a0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
325b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
325c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
325d0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
325e0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
325f0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
32600 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
32610 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
32620 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
32630 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
32640 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
32650 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
32660 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
32670 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
32680 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
32690 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
326a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
326b0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
326c0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
326d0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
326e0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
326f0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
32700 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
32710 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
32720 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
32730 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
32740 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
32750 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
32760 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
32770 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
32780 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
32790 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
327a0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
327b0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
327c0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
327d0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
327e0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
327f0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
32800 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
32810 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
32820 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
32830 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
32840 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
32850 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
32860 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
32870 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
32880 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
32890 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
328a0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
328b0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
328c0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
328d0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
328e0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
328f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
32900 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
32910 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32920 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
32930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
32940 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
32950 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
32960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
32970 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
32980 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
32990 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
329a0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
329b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
329c0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
329d0 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66  red using any of
329e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
329f0 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
32a00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
32a10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
32a20 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
32a30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
32a40 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20  pare16_v3()] or 
32a50 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
32a60 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
32a70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32a80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32a90 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
32aa0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
32ab0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
32ac0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
32ad0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
32ae0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
32af0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
32b00 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
32b10 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
32b20 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
32b30 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
32b40 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
32b50 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
32b60 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58  ng the newer "vX
32b70 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  " interfaces.** 
32b80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32b90 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
32ba0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
32bb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32bc0 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  16_v3()],.** [sq
32bd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32be0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
32bf0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
32c00 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
32c10 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
32c20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32c30 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
32c40 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
32c50 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  X" interface is 
32c60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
32c70 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
32c80 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
32c90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
32ca0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
32cb0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
32cc0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
32cd0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
32ce0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
32cf0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
32d00 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
32d10 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
32d20 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
32d30 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
32d40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
32d50 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
32d60 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
32d70 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
32d80 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
32d90 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
32da0 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
32db0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
32dc0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
32dd0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
32de0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
32df0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
32e00 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
32e10 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
32e20 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
32e30 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
32e40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
32e50 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
32e60 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
32e70 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
32e80 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
32e90 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
32ea0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
32eb0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
32ec0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
32ed0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
32ee0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
32ef0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
32f00 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
32f10 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
32f20 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
32f30 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
32f40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
32f50 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
32f60 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
32f70 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
32f80 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
32f90 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
32fa0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
32fb0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
32fc0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
32fd0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
32fe0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
32ff0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33000 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
33010 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
33020 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
33030 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
33040 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
33050 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
33060 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
33070 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
33080 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
33090 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
330a0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
330b0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
330c0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
330d0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
330e0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
330f0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
33100 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
33110 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33120 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
33130 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
33140 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
33150 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
33160 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
33170 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
33180 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
33190 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
331a0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
331b0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
331c0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
331d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
331e0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
331f0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
33200 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
33210 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
33220 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
33230 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
33240 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
33250 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
33260 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
33270 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
33280 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
33290 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
332a0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
332b0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
332c0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
332d0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
332e0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
332f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
33300 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
33310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33320 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
33330 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
33340 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
33350 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
33360 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
33370 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
33380 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
33390 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
333a0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
333b0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
333c0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
333d0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
333e0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
333f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33400 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
33410 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
33420 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33430 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
33440 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
33450 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
33460 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
33470 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
33480 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
33490 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
334a0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
334b0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
334c0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
334d0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
334e0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
334f0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
33500 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
33510 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
33520 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
33530 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
33540 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
33550 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
33560 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
33570 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
33580 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
33590 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
335a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
335b0 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
335c0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
335d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
335e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
335f0 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
33600 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
33610 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
33620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
33630 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
33640 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
33650 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
33660 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
33670 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
33680 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  r [version 3.6.2
33690 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  3.1] ([dateof:3.
336a0 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69  6.23.1],.** sqli
336b0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
336c0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
336d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
336e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
336f0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
33700 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
33710 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
33720 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
33730 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
33740 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
33750 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
33760 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
33770 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
33780 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
33790 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
337a0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
337b0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
337c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
337d0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
337e0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
337f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
33800 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
33810 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
33820 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
33830 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
33840 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
33850 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
33860 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
33870 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
33880 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
33890 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
338a0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
338b0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
338c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
338d0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
338e0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
338f0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
33900 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
33910 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
33920 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
33930 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
33940 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
33950 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
33960 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
33970 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
33980 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
33990 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
339a0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
339b0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
339c0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
339d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
339e0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
339f0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
33a00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
33a10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
33a20 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71  are_v3()] or [sq
33a30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33a40 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
33a50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
33a60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
33a70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
33a80 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
33a90 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
33aa0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
33ab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33ac0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
33ad0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
33ae0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
33af0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
33b00 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
33b10 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
33b20 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
33b30 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  f the "vX" inter
33b40 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65  faces is recomme
33b50 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
33b60 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
33b70 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
33b80 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
33b90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
33ba0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
33bb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33bc0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
33bd0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33be0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
33bf0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
33c00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33c10 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
33c20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
33c30 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
33c40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
33c50 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
33c60 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
33c70 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
33c80 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
33c90 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
33ca0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
33cb0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
33cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
33cd0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
33ce0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
33cf0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33d00 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
33d10 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33d20 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
33d30 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
33d40 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
33d50 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
33d60 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33d70 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
33d80 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
33d90 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
33da0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
33db0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
33dc0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
33dd0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33de0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
33df0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
33e00 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
33e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33e20 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
33e30 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
33e40 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
33e50 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
33e60 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
33e70 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
33e80 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
33e90 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
33ea0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
33eb0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
33ec0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
33ed0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
33ee0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
33ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
33f00 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
33f10 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
33f30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33f40 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
33f50 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
33f60 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
33f70 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
33f80 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
33f90 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
33fa0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
33fb0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
33fc0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
33fd0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
33fe0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
33ff0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
34000 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
34010 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
34020 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
34030 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
34040 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
34050 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
34060 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
34070 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
34080 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
34090 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
340a0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
340b0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
340c0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
340d0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
340e0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
340f0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
34100 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
34110 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
34120 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
34130 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
34140 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
34150 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
34160 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
34170 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
34180 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
34190 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
341a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
341b0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
341c0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
341d0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
341e0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
341f0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
34200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
34210 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
34220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
34230 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
34240 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
34250 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
34260 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
34270 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
34280 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
34290 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
342a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53  _stmt.**.** <b>S
342b0 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c  ummary:</b>.** <
342c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c  blockquote><tabl
342d0 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70  e border=0 cellp
342e0 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61  adding=0 cellspa
342f0 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c  cing=0>.** <tr><
34300 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34310 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64  lumn_blob</b><td
34320 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20  >&rarr;<td>BLOB 
34330 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
34340 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34350 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74  umn_double</b><t
34360 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c  d>&rarr;<td>REAL
34370 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34380 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34390 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  lumn_int</b><td>
343a0 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
343b0 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
343c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
343d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
343e0 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  64</b><td>&rarr;
343f0 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47  <td>64-bit INTEG
34400 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
34410 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34420 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c  column_text</b><
34430 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
34440 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  -8 TEXT result.*
34450 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34470 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  16</b><td>&rarr;
34480 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20  <td>UTF-16 TEXT 
34490 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
344a0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
344b0 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64  umn_value</b><td
344c0 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72  >&rarr;<td>The r
344d0 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20  esult as an .** 
344e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75  [sqlite3_value|u
344f0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34500 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34510 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62  ..** <tr><td>&nb
34520 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  sp;<td>&nbsp;<td
34530 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c  >&nbsp;.** <tr><
34540 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34550 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74  lumn_bytes</b><t
34560 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65  d>&rarr;<td>Size
34570 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72   of a BLOB.** or
34580 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65   a UTF-8 TEXT re
34590 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a  sult in bytes.**
345a0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
345b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
345c0 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f  16&nbsp;&nbsp;</
345d0 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b  b>.** <td>&rarr;
345e0 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e  &nbsp;&nbsp;<td>
345f0 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a  Size of UTF-16.*
34600 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a  * TEXT in bytes.
34610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34630 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
34640 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61  td>Default.** da
34650 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
34660 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  sult.** </table>
34670 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
34680 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c  .** <b>Details:<
34690 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  /b>.**.** ^These
346a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
346b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
346c0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
346d0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
346e0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
346f0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
34700 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
34710 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
34720 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
34730 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
34740 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
34750 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
34760 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
34770 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
34780 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
34790 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
347a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
347b0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
347c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
347d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
347e0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
347f0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
34800 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
34810 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
34820 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
34830 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
34840 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
34850 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
34860 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
34870 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
34880 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
34890 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
348a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
348b0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
348c0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
348d0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
348e0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
348f0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
34900 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
34910 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
34920 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
34930 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
34940 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34950 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
34960 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
34970 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
34980 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
34990 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
349a0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
349b0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
349c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
349d0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
349e0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
349f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
34a00 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
34a10 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34a20 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
34a30 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
34a40 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
34a50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34a60 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
34a70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
34a80 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
34a90 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
34aa0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
34ab0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34ac0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
34ad0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
34ae0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
34af0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
34b00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
34b10 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
34b20 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
34b30 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
34b40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
34b50 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
34b60 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
34b70 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
34b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
34b90 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73  t six interfaces
34ba0 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65   (_blob, _double
34bb0 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20  , _int, _int64, 
34bc0 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74  _text, and _text
34bd0 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75  16).** each retu
34be0 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  rn the value of 
34bf0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
34c00 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61  in a specific da
34c10 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a  ta format.  If.*
34c20 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  * the result col
34c30 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69  umn is not initi
34c40 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75  ally in the requ
34c50 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f  ested format (fo
34c60 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66  r example,.** if
34c70 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72   the query retur
34c80 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75  ns an integer bu
34c90 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  t the sqlite3_co
34ca0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65  lumn_text() inte
34cb0 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64  rface.** is used
34cc0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
34cd0 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61  value) then an a
34ce0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
34cf0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
34d00 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
34d10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34d20 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
34d30 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
34d40 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
34d50 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
34d60 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
34d70 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
34d80 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
34d90 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
34da0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
34db0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
34dc0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
34dd0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
34de0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
34df0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
34e00 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65  NULL]..** The re
34e10 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71  turn value of sq
34e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34e30 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
34e40 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a  to decide which.
34e50 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ** of the first 
34e60 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68  six interface sh
34e70 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
34e80 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75  extract the colu
34e90 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65  mn value..** The
34ea0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
34eb0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
34ec0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
34ed0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
34ee0 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74  o.** automatic t
34ef0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
34f00 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f  have occurred fo
34f10 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71  r the value in q
34f20 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66  uestion.  .** Af
34f30 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
34f40 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c  rsion, the resul
34f50 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c  t of calling sql
34f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34f70 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
34f80 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c  ed, though harml
34f90 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ess.  Future.** 
34fa0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
34fb0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
34fc0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
34fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34fe0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
34ff0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
35000 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
35010 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
35020 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69  B or a TEXT stri
35030 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ng, then the sql
35040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35050 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  s().** or sqlite
35060 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35070 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61  () interfaces ca
35080 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74  n be used to det
35090 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a  ermine the size.
350a0 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20  ** of that BLOB 
350b0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  or string..**.**
350c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
350d0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
350e0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
350f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
35100 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
35110 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
35120 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35130 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
35140 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35150 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35160 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
35170 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35180 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
35190 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
351a0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
351b0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
351c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
351d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
351e0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
351f0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
35200 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35210 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
35220 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
35230 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
35240 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
35250 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
35260 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
35270 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35280 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
35290 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
352a0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
352b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
352c0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
352d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
352e0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
352f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
35300 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
35310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35320 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
35330 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35340 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
35350 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
35360 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35370 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
35380 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
35390 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
353a0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
353b0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
353c0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
353d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
353e0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
353f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35400 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
35410 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35420 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
35430 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
35440 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
35450 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
35460 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
35470 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
35480 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
35490 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
354a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
354b0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
354c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
354d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
354e0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
354f0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
35500 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
35510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35520 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
35530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35540 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
35550 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
35560 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
35570 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
35580 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
35590 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
355a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
355b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
355c0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
355d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
355e0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
355f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
35600 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
35610 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
35620 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
35630 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
35640 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
35650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35660 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
35670 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
35680 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
35690 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
356a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
356b0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
356c0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
356d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
356e0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
356f0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
35700 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
35710 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
35720 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
35730 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
35740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35750 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
35760 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35770 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
35780 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
35790 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
357a0 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
357b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
357c0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
357d0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
357e0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
357f0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
35800 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
35810 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
35820 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
35830 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35840 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
35850 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
35860 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
35870 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
35880 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
35890 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
358a0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
358b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
358c0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
358d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
358e0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
358f0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
35900 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
35910 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
35920 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c  * Hence, the sql
35930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
35940 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  e() interface.**
35950 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c   is normally onl
35960 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20  y useful within 
35970 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
35980 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69  on of .** [appli
35990 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
359a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
359b0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
359c0 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a  ], not within.**
359d0 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69   top-level appli
359e0 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a  cation code..**.
359f0 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75  ** The these rou
35a00 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70  tines may attemp
35a10 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
35a20 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
35a30 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72   result..** ^For
35a40 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
35a50 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
35a60 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
35a70 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
35a80 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
35a90 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
35aa0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
35ab0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
35ac0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
35ad0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
35ae0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
35af0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
35b00 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
35b10 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
35b20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
35b30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
35b40 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
35b50 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
35b60 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
35b70 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
35b80 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
35b90 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
35ba0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
35bb0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35bc0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
35bd0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
35be0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
35bf0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
35c00 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
35c10 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
35c20 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35c30 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
35c40 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
35c50 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
35c60 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
35c70 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
35c80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
35c90 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
35ca0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
35cb0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
35cc0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
35cd0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
35ce0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
35cf0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
35d00 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
35d10 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
35d20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
35d30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35d40 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
35d50 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
35d60 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35d70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
35d80 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
35d90 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
35da0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35db0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35dc0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
35dd0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
35de0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
35df0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35e00 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35e10 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
35e20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
35e30 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35e40 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35e50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
35e60 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
35e70 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35e80 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35e90 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35ea0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35eb0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
35ec0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35ed0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35ee0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
35ef0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
35f00 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
35f10 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
35f20 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
35f30 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
35f40 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
35f50 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
35f60 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
35f70 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
35f80 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
35f90 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
35fa0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
35fb0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
35fc0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
35fd0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
35fe0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
35ff0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
36000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36010 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
36020 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
36030 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
36040 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
36050 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
36060 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
36070 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
36080 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
36090 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
360a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
360b0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
360c0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
360d0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
360e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
360f0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
36100 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36110 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
36120 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
36130 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
36140 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
36150 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
36160 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
36170 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
36180 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
36190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
361a0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
361b0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
361c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
361d0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
361e0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
361f0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
36200 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
36210 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
36220 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
36230 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
36240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36250 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
36260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36270 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
36280 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
36290 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
362a0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
362b0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
362c0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
362d0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
362e0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
362f0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
36300 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
36310 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
36320 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
36330 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
36340 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
36350 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
36360 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
36370 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
36380 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
36390 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
363a0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
363b0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
363c0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
363d0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
363e0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
363f0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
36400 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
36410 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
36420 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
36430 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
36440 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
36450 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
36460 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
36470 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
36480 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
36490 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
364a0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
364b0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
364c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
364d0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
364e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
364f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
36500 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
36510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36520 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
36530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36540 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
36550 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
36560 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
36570 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
36580 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
36590 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
365a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
365b0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
365c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
365d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
365e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
365f0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
36600 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
36610 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
36620 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
36630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36640 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
36650 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
36660 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
36670 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
36680 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
36690 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
366a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
366b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
366c0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
366d0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
366e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
366f0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
36700 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
36710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36720 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
36730 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
36740 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
36750 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
36760 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
36770 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
36780 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
36790 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
367a0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
367b0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
367c0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
367d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
367e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
367f0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
36800 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
36810 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
36820 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
36830 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
36840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
36850 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70  o not pass the p
36860 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
36870 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
36880 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
36890 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
368a0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
368b0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
368c0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
368d0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
368e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
368f0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
36900 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
36910 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
36920 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
36930 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
36940 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
36950 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
36960 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
36970 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
36980 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
36990 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
369a0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
369b0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
369c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
369d0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
369e0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
369f0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
36a00 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
36a10 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
36a20 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36a30 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
36a40 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
36a50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36a60 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36a70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
36a80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36a90 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
36aa0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
36ab0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
36ac0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36ad0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
36ae0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
36af0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
36b00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36b10 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
36b20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
36b30 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
36b40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36b50 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
36b60 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
36b70 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
36b80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36ba0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
36bb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36bc0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
36bd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36be0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36bf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
36c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
36c10 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
36c20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
36c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
36c40 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
36c50 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
36c60 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  t.** DESTRUCTOR:
36c70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
36c80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36c90 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
36ca0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
36cb0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
36cc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
36cd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
36ce0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
36cf0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
36d00 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
36d10 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
36d20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
36d30 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
36d40 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
36d50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36d60 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
36d70 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
36d80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
36d90 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
36da0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
36db0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
36dc0 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
36dd0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
36de0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
36df0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
36e00 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
36e10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36e20 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
36e30 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
36e40 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
36e50 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
36e60 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
36e70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36e80 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
36e90 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
36ea0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
36eb0 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
36ec0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
36ed0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
36ee0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
36ef0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
36f00 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
36f10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
36f20 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
36f30 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
36f40 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
36f50 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
36f60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
36f70 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
36f80 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
36f90 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
36fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
36fb0 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
36fc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36fd0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
36fe0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
36ff0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
37000 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
37010 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
37020 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
37030 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
37040 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
37050 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
37060 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
37070 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
37080 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
37090 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
370a0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
370b0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
370c0 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
370d0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
370e0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
370f0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
37100 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
37110 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
37120 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
37130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37140 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
37150 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
37160 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
37170 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
37180 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37190 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
371a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
371b0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
371c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
371d0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
371e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
371f0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
37200 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
37210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
37220 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
37230 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
37240 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
37250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
37260 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
37270 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
37280 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
37290 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
372a0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
372b0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
372c0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
372d0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
372e0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
372f0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
37300 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37310 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
37320 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
37330 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
37340 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
37350 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
37360 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
37370 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
37380 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37390 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
373a0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
373b0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
373c0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
373d0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
373e0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
373f0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
37400 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
37410 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
37420 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
37430 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
37440 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
37450 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
37460 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
37470 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37480 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
37490 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
374a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
374b0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
374c0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
374d0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
374e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
374f0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
37500 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
37510 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
37520 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
37530 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
37540 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
37550 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
37560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
37570 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
37580 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
37590 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
375a0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
375b0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
375c0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
375d0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
375e0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
375f0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
37600 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37610 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
37620 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
37630 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37640 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
37650 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
37660 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
37670 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
37680 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
37690 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
376a0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
376b0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
376c0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
376d0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
376e0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
376f0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
37700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
37710 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
37720 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
37730 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
37740 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
37750 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
37760 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
37770 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
37780 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
37790 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
377a0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
377b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
377c0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
377d0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
377e0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
377f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37800 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
37810 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
37820 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
37830 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37840 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
37850 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
37860 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
37870 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
37880 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
37890 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
378a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
378b0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
378c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
378d0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
378e0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
378f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37900 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
37910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
37920 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
37930 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37940 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
37950 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
37960 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
37970 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
37980 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
37990 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
379a0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
379b0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
379c0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
379d0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
379e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
379f0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
37a00 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
37a10 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
37a20 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
37a30 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
37a40 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
37a50 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
37a60 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
37a70 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
37a80 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
37a90 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
37aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
37ab0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
37ac0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
37ad0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
37ae0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
37af0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
37b00 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
37b10 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
37b20 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
37b30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37b40 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
37b50 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
37b60 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
37b70 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
37b80 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
37b90 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
37ba0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
37bb0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
37bc0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
37bd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
37be0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
37bf0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
37c00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
37c10 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
37c20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
37c30 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
37c40 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
37c50 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
37c60 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
37c70 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
37c80 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
37c90 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
37ca0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
37cb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
37cc0 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
37cd0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
37ce0 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
37cf0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
37d00 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
37d10 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
37d20 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
37d30 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
37d40 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
37d50 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
37d60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
37d70 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
37d80 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
37d90 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
37da0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
37db0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
37dc0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
37dd0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
37de0 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
37df0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
37e00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
37e10 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
37e20 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
37e30 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
37e40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
37e50 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
37e60 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
37e70 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
37e80 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
37e90 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
37ea0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37eb0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
37ec0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
37ed0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
37ee0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
37ef0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
37f00 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
37f10 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
37f20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
37f30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37f40 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
37f50 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
37f60 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
37f70 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
37f80 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
37f90 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
37fa0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
37fb0 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
37fc0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
37fd0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
37fe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
37ff0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
38000 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
38010 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
38020 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
38030 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
38040 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
38050 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
38060 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
38070 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
38080 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
38090 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
380a0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
380b0 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
380c0 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
380d0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
380e0 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
380f0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
38100 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
38110 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
38120 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
38130 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
38140 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
38150 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
38160 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
38170 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
38180 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
38190 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
381a0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
381b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
381c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
381d0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
381e0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
381f0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
38200 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
38210 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
38220 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
38230 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
38240 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
38250 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
38260 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
38270 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
38280 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
38290 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
382a0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
382b0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
382c0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
382d0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
382e0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
382f0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
38300 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
38310 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
38320 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
38330 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
38340 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
38350 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
38360 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
38370 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
38380 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
38390 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
383a0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
383b0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
383c0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
383d0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
383e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
383f0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
38400 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
38410 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
38420 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
38430 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
38440 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
38450 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
38460 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
38470 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
38480 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
38490 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
384a0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
384b0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
384c0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
384d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
384e0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
384f0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
38500 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
38510 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
38520 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38530 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
38540 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
38550 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
38560 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
38570 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
38580 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
38590 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
385a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
385b0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
385c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
385d0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
385e0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
385f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
38600 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38610 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
38620 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
38630 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
38640 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
38650 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
38660 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
38670 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
38680 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
38690 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
386a0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
386b0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
386c0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
386d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
386e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
386f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
38700 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
38710 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
38720 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
38730 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
38740 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
38750 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
38760 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
38770 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
38780 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
38790 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
387a0 63 68 20 74 68 61